clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/doc/THREE-BIRD-ARCHITECTURE.md
Operator & Codex 50a915c414 Drop Astro docs path compatibility noise (Codex) 
Remove the ASTRO_SITE_PATH alias and stale STRIPPED/refactor comments now that CMS_DOCS_SITE_PATH is the canonical docs project path.

---
Build: pass | Tests: pass — 2372 passed (704 files)

---
Build: pass | Tests: pass — 2372 passed (704 files)

---
Build: pass | Tests: pass — 2372 passed (704 files)

---
Build: pass | Tests: pass — 2372 passed (704 files)
2026-05-10 20:47:10 +02:00

400 lines
16 KiB
Markdown
Raw Permalink Blame History

# 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/
Reference in a new issue View git blame Copy permalink