Architettura Docs

BlackTrails Docs: Architettura & Workflow “Headless”

Documento di riferimento per la gestione, sicurezza e pubblicazione dei documenti.

1. Core Concept (The Zen Architecture)

Il sistema opera come un CMS Headless proprietario.

Componente	Ruolo
GitHub	Source of Truth (Backend)
Dashboard	Editor (CMS) - Staff + Agenti AI
Astro	Viewer (Frontend) - docs.blacktrails.io
Cloudflare	Security Layer (Zero Trust)

2. Struttura Dati (File System)

La gerarchia delle cartelle su GitHub definisce l’accesso.

/docs/...                    → Pubblico (tutti)
/private/                    → Protetto (Cloudflare)
  └── /*                     → Solo Admin (Francesco)
  └── /area-x/elements       → Admin + Collaboratori (Elena)

3. Workflow Pubblicazione

3.1 Scrittura & Commit

Chi scrive:

• Staff: Francesco, Elena
• AI Agents: Claude, GPT-4 (via Dashboard)

Dove:

1. Locale: E:\blacktrails-docs\src\content\docs\
2. Push: git push origin main
3. GitHub riceve il commit

3.2 Build & Deploy (Automatico)

Cloudflare Pages:

1. Webhook GitHub → Trigger build
2. Astro build (npm run build)
3. Deploy su docs.blacktrails.io
4. Tempo: ~60 secondi

3.3 Security Layer

Cloudflare Access:

• /private/* → Protetto con email whitelist
• Accesso: [email protected]
• Zero Trust: verifica ogni richiesta

4. Tech Stack

Framework: Astro v5.16.6
Theme: Starlight v0.33
Design: Dark Forest System
Hosting: Cloudflare Pages
Repository: GitHub (SSH)
Auth: Cloudflare Zero Trust

5. Flusso Operativo (Claude Agent)

User Request → Claude Code
             ↓
   1. Read/Write Files Locale
   2. Git Commit + Push
   3. Wait Build (~60s)
   4. Verify Deploy

6. File Types

Tipo	Formato	Uso
Articoli pubblici	.md / .mdx	Philosophy, Ecosystem
Documenti privati	.md	Budget, Note, Architettura
Config	.mjs	Sidebar, i18n, routes
Style	.css	Dark Forest theme

7. Bilinguismo (i18n)

SCENARIO A (Root Locale):

• English: / (root)
• Italian: /it/
• Private: solo /private/ (no traduzione)

Sidebar:

translations: { it: 'Area Riservata' }

8. URLs & Routing

https://docs.blacktrails.io/
├── /                           # Home EN
├── /it/                        # Home IT
├── /philosophy/rhama/          # Pubblico EN
├── /it/filosofia/rhama/        # Pubblico IT
├── /private/                   # Caveau (protetto)
└── /private/area-x/            # Area X (protetto)

9. Maintenance

Update Stack:

npm update
npm audit fix

Rebuild Indexes:

npm run build

Git Operations:

git status
git add .
git commit -m "message"
git push origin main

10. Security Best Practices

1. Mai committare .env → .gitignore attivo
2. SSH key protetta → ~/.ssh/id_ed25519
3. Cloudflare Access → whitelist email
4. Private files → solo in /private/

---

🔒 Documento interno - Solo Francesco

Ultimo aggiornamento: 18 Dicembre 2025