# Three-Bird Documentation Architecture

**Status:** MVP Implementation Complete (April 2026)  
**Goal:** Codify documentation localization for Pi/Aider automation  
**Scope:** EN + SLO (MVP), roadmap: DE/SRB/CRO/BIH/RU/ZN/BR

---

## Overview

The **three-bird architecture** decouples documentation concerns into three independent systems that work together:

1. **🐦 Crowdin** — Localization source of truth. Single English source, managed translations in 9 languages.
2. **🐦 Astro Starlight** — Static site generator. Builds multilingual docs from Crowdin translations + English.
3. **🐦 Strapi CMS** (deferred) — Content backend for rich media/structured content. Blocked by FreeBSD native binding issues at the time of this design; revisit if Strapi support is reconsidered.

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                      ENGLISH SOURCE DOCS                        │
│                    docs/public/**.md (repo)                     │
│                                                                 │
│  - install/                 - architecture/                     │
│  - reference/              - getting-started/                   │
│  - api/                    - troubleshooting/                   │
└────────────────────────────┬────────────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │ Crowdin Push    │
                    │ (./scripts/     │
                    │  crowdin-sync   │
                    │  .sh --push)    │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         │             ┌─────▼──────┐            │
         │             │ Crowdin     │            │
         │             │ Localization│            │
         │             │ Platform    │            │
         │             │ (883714)    │            │
         │             └─────┬──────┘            │
         │                   │                   │
┌────────▼────────┐  ┌──────▼──────┐  ┌────────▼────────┐
│ Slovenian (SLO) │  │ German (DE)  │  │ Croatian (HR)   │
│ 100% default    │  │ Roadmap      │  │ Roadmap         │
└────────┬────────┘  └──────┬──────┘  └────────┬────────┘
         │                  │                   │
         └──────────────────┼───────────────────┘
                            │
                 ┌──────────▼──────────┐
                 │ Crowdin Pull        │
                 │ (./scripts/         │
                 │  crowdin-sync       │
                 │  .sh --pull)        │
                 └──────────┬──────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
    ┌────▼────┐        ┌────▼────┐       ┌────▼────┐
    │docs/    │        │docs/    │       │docs/    │
    │public/  │        │public/  │       │public/  │
    │sl/      │        │de/      │       │hr/      │
    └────┬────┘        └────┬────┘       └────┬────┘
         │                  │                  │
         └──────────────────┼──────────────────┘
                            │
           ┌────────────────▼────────────────┐
           │ Astro Starlight Build           │
           │ (npm run build in               │
           │  bootstrap/cms/clawdie-docs/)   │
           │                                 │
           │ - Multi-locale config           │
           │ - Sidebar i18n                  │
           │ - Static site generation        │
           └────────────────┬────────────────┘
                            │
           ┌────────────────▼────────────────┐
           │ Static Site Output              │
           │ (dist/)                         │
           │                                 │
           │ /              (SLO)            │
           │ /en/           (English)        │
           │ /de/           (German)         │
           │ /hr/           (Croatian)       │
           │ ... (others)                    │
           └────────────────┬────────────────┘
                            │
           ┌────────────────▼────────────────┐
           │ Deploy to nginx                 │
           │ (/usr/local/www/clawdie/docs)   │
           └────────────────┬────────────────┘
                            │
           ┌────────────────▼────────────────┐
           │ PUBLIC: docs.clawdie.si         │
           └─────────────────────────────────┘
```

---

## MVP Decision: Markdown-Only (Option A)

**Chosen Approach:** Ship with Crowdin + Astro (no Strapi for now)

### Why Markdown-Only First

| Factor                | Markdown-Only                | Strapi Path                    |
| --------------------- | ---------------------------- | ------------------------------ |
| **Shipping time**     | 1-2 weeks                    | 3-4 weeks                      |
| **Dependencies**      | Standard tools               | FreeBSD blocker                |
| **MVP feature set**   | ✓ Full (docs + translations) | ✗ Incomplete (no image upload) |
| **Maintenance**       | Simple (pure markdown)       | Complex (CMS + API)            |
| **Codifiable for Pi** | ✓ Yes                        | ⚠ Conditional                  |

### What Ships in MVP

```
✓ Crowdin localization platform (LIVE)
✓ Markdown sources in docs/public/
✓ Automated Crowdin → Astro pipeline
✓ Multi-language static site
✓ English (EN) + Slovenian (SLO) default
✓ Roadmap languages configured (not translated yet)
✓ Pi/Aider automation for sync & deploy
```

### What Defers (Phase 2+)

```
✗ Strapi CMS (blocked by FreeBSD native bindings)
✗ Rich media uploads (requires Strapi + sharp image processing)
✗ Structured content types (Page, Guide, BlogPost)
✗ CMS-driven updates (once Strapi is viable)
```

---

## Implementation Status

### ✓ Complete

| Component                 | Location                                                           | Status                        |
| ------------------------- | ------------------------------------------------------------------ | ----------------------------- |
| **Crowdin Script**        | `./scripts/crowdin-sync.sh`                                        | ✓ Working (push/pull/status)  |
| **Crowdin Config**        | `.crowdin.yml`                                                     | ✓ Configured (project 883714) |
| **English Source Docs**   | `docs/public/**/*.md`                                              | ✓ 42+ files ready             |
| **Skill Documentation**   | `.agent/skills/docs-localization-pipeline/SKILL.md`                | ✓ Complete                    |
| **Setup Script**          | `.agent/skills/docs-localization-pipeline/setup-clawdie-docs.sh`     | ✓ Tested                      |
| **Pipeline Orchestrator** | `.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh` | ✓ Ready                       |
| **Skill README**          | `.agent/skills/docs-localization-pipeline/README.md`               | ✓ Complete                    |

### ⏳ Pending (User Action)

| Task                            | Owner       | Timeline        |
| ------------------------------- | ----------- | --------------- |
| Create Crowdin translators      | User        | ASAP            |
| Push English sources to Crowdin | Pi/Aider    | This week       |
| Assign translation languages    | Translators | This week       |
| Reach 80% completion milestone  | Translators | 1-2 weeks       |
| First pull & build              | Pi/Aider    | After milestone |
| Deploy to docs.clawdie.si       | Pi/Aider    | After build     |
| Setup weekly sync schedule      | Pi/Aider    | Ongoing         |

---

## How It Works

### Daily Workflow (Codified for Pi/Aider)

```bash
# 1. English docs are edited in /docs/public/**.md
# 2. Crowdin sync pushed (via Pi or cron)
./scripts/crowdin-sync.sh --push

# 3. Crowdin translators update translations
# 4. Weekly sync pulls translations
./scripts/crowdin-sync.sh --pull

# 5. Astro builds multilingual site
cd /home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs && npm run build

# 6. Deploy to nginx
sudo cp -r dist/* /usr/local/www/clawdie/docs/
sudo nginx -s reload
```

**Automated by Pi/Aider:**

```bash
pi "sync translations and rebuild documentation site"
# → Executes: orchestrate-pipeline.sh --all
```

### Configuration Codification

All automation is controlled by environment variables in `.env`:

```bash
# Crowdin API token
CROWDIN_PERSONAL_TOKEN=tskey-xxx

# Paths
CMS_DOCS_SITE_PATH=/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs
DOCS_DEPLOY_TARGET=/usr/local/www/clawdie/docs

# Thresholds
DOCS_MIN_COMPLETION=80  # Min % before auto-deploy
```

---

## File Structure

### Skill Assets

```
.agent/skills/docs-localization-pipeline/
├── SKILL.md                      # Detailed architecture & reference
├── README.md                     # Quick start & troubleshooting
├── setup-clawdie-docs.sh          # Bootstrap Astro project
└── orchestrate-pipeline.sh      # Full pipeline automation
```

### Documentation

```
doc/
├── THREE-BIRD-ARCHITECTURE.md   # This file (overview)
└── [other docs]

docs/public/                      # English source
├── install/
├── architecture/
├── reference/
└── [content sections]

docs/public/{lang}/              # Crowdin translations
├── en/                          # English
├── de/                          # German (roadmap)
├── hr/                          # Croatian (roadmap)
└── [others]
```

### Astro Project

```
/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs/
├── astro.config.mjs            # Multi-locale Starlight config
├── package.json
├── src/
│   ├── content/
│   │   ├── config.ts           # Content collections
│   │   ├── docs/
│   │   │   ├── en → docs/public/en (symlink)
│   │   │   ├── de → docs/public/de (symlink)
│   │   │   └── [others]
│   │   └── i18n/
│   │       ├── en.json
│   │       ├── de.json
│   │       └── sl.json
│   ├── components/
│   └── styles/
└── dist/                       # Build output (after npm run build)
```

---

## Integration with clawdie-ai Controlplane

### Config Values (src/config.ts)

```typescript
// CMS/Docs paths
export const CMS_JAIL_IP = envConfig.WARDEN_CMS_IP || '10.0.0.4';
export const CMS_DOCS_SITE_PATH =
  envConfig.CMS_DOCS_SITE_PATH ||
  '/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs';
export const CMS_WEBROOT = envConfig.CMS_WEBROOT || '/usr/local/www/clawdie';

// Used by jail runtime for mounting docs build
```

### Jail Networking

```
10.0.0.3  = db (PostgreSQL)
10.0.0.4  = cms (Strapi later, Astro build for now)
10.0.0.7  = web (nginx)

nginx serves:
  - /              → docs.clawdie.si (from Astro build)
  - /api           → Strapi (when available)
```

---

## Phase 2: Strapi CMS Integration (Deferred)

### Why Deferred

FreeBSD lacks prebuilt binaries for native Node.js modules that Strapi depends on:

- `sharp` (image processing)
- `esbuild` (bundling)
- `@swc/core` (transpilation)

**Workaround:** Compile libvips from `/usr/ports/graphics/vips` (2-3 hours on first build).

**Recommendation:** Ship MVP first, add Strapi later when image upload is needed.

### What Strapi Will Add

```
Enhanced CMS Features:
✓ Rich media upload (images, videos)
✓ Structured content types (Page, Guide, BlogPost)
✓ API endpoints for dynamic content
✓ Built-in user authentication
✓ Content versioning & publishing workflow

Integration:
- Crowdin syncs content to Strapi API
- Astro queries Strapi for rich media
- CMS-driven metadata (authors, dates, categories)
```

---

## Automation Examples

### Example 1: Manual Full Pipeline

```bash
# One-command deployment
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --all
```

### Example 2: Scheduled Weekly Sync

```bash
# Add to crontab
0 9 * * MON /home/clawdie/clawdie-ai/.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --pull
```

### Example 3: Pi/Aider Orchestration

```bash
# Natural language command
pi "Update documentation translations and rebuild the site"

# Aider auto-commit
aider --auto-commits \
  --message "Sync translations from Crowdin" \
  "docs/public/"
```

### Example 4: GitHub Actions

See `.github/workflows/crowdin-sync.yml` (optional CI/CD).

---

## Success Metrics

### MVP Launch

- [ ] Crowdin project 883714 has English sources uploaded
- [ ] Translators assigned to at least SLO + EN
- [ ] `orchestrate-pipeline.sh --all` produces live site at docs.clawdie.si
- [ ] Pi can execute: `pi "sync and rebuild docs"`
- [ ] Weekly automation in place

### Phase 2 (Post-MVP)

- [ ] DE, HR, SR translations at 80%+
- [ ] Automated weekly syncs running
- [ ] Strapi ready (libvips compiled)
- [ ] CMS content integration tested

---

## Quick Links

| Resource                | Path                                        | Purpose                       |
| ----------------------- | ------------------------------------------- | ----------------------------- |
| **Skill**               | `.agent/skills/docs-localization-pipeline/` | Executable automation         |
| **Architecture Doc**    | `doc/THREE-BIRD-ARCHITECTURE.md`            | This file                     |
| **Crowdin Sync Script** | `./scripts/crowdin-sync.sh`                 | Manual push/pull/status       |
| **Crowdin Config**      | `.crowdin.yml`                              | Project settings              |
| **AGENTS.md**           | `AGENTS.md`                                 | Pi/Aider harness guidance     |
| **Astro Example**       | `examples/astro-cv/`                        | Reference Starlight setup     |

---

## References

- **Crowdin:** https://crowdin.com/project/clawdie-ai
- **Astro Starlight:** https://starlight.astro.build/
- **Crowdin API:** https://developer.crowdin.com/api/