# ADR — Architecture Decision Records

Format Architecture Decision Record. Une entree par decision structurelle.

---

## ADR-001 — Stack composite : Docmost (wiki) + Baserow (DBs)

**Statut** : Accepte le 2026-05-07
**Decideurs** : Le user (AdminSys/DevOps) + BYAN (consulting)

### Contexte

Aucun projet OSS unique ne couvre :
- Users illimites self-host (out : AFFiNE 10-seat, AppFlowy 1-user)
- Bidirec + DBs multi-vues + team workspaces simultanement
- Budget recurrent zero (out : AFFiNE Team License)

### Decision

Combiner deux outils OSS matures :
- **Docmost** pour le wiki collaboratif (AGPL, users illimites, team workspaces, share links natifs)
- **Baserow** pour les DBs structurees (MIT core, users illimites, vues multiples, rollups, relations)

Et construire un **bridge service** custom Node TS pour unifier l'UX de surface (l'UI Baserow reste cachee cote utilisateur final).

### Alternatives ecartees

1. **AFFiNE Team License paid** : ~2200€/an recurrent, lock-in vendor.
2. **Custom DB engine sur Docmost** : 4-6 mois dev (~30-60k€), reinvention de la roue.
3. **Notion (cloud)** : pas self-host.
4. **Outline + add bidirec custom** : license BSL bloque usage commercial.
5. **AppFlowy paid** : disqualifie pour stack Flutter (recrutement difficile, pas web-first).

### Consequences

**Positives**
- Zero recurrent licensing cost (juste l'infra ~30€/mois VPS)
- Stack mainstream TS/NestJS/React/Tiptap pour Docmost et Python/Django pour Baserow
- Decouplage permet de remplacer Docmost ou Baserow sans tout refaire
- Baserow couvre les besoins DBs du cas (multi-vues, relations, rollups, formules) parmi les Airtable-likes OSS evalues

**Negatives**
- Deux services a maintenir au lieu d'un
- Bridge service = code custom a ecrire et maintenir
- Performance : appels HTTP entre Docmost et Baserow (mitige par cache Redis)
- Risque scope creep sur le bridge (tentation de reproduire 100% de Notion)

**A surveiller**
- Si Docmost ajoute des DBs natives (pas dans roadmap actuelle), reevaluer la valeur de Baserow
- Si AFFiNE OSS leve sa limite 10-seat, reevaluer le path A

---

## ADR-002 — Path B (UX quasi-unified) plutot que Path A (deux mondes)

**Statut** : Accepte le 2026-05-07

### Contexte

Path A (cross-link URL externe entre Docmost et Baserow) demande **2-4 semaines** mais expose l'UI Baserow aux utilisateurs (jonglage entre deux applis).

Path B (Tiptap nodes custom + API Baserow) demande **2-3 mois pour un fullstack senior, 4-6 mois pour AdminSys/DevOps solo** mais offre une UX unifiee.

### Decision

**Path B** retenu. Le user accepte la courbe d'apprentissage Tiptap/React et la timeline plus longue contre une UX qui ne disrupt pas l'experience metier.

### Consequences

- Phase 1 (Mois 1) : stack vanilla utilisable telle quelle, l'equipe peut commencer a alimenter le wiki et les DBs sans bridge
- Phase 2 (Mois 2-6) : iteration progressive sur les nodes Tiptap custom selon la douleur reelle des utilisateurs
- Risque : tentation d'aller direct au "tout brillant" sans valider l'usage. Garde-fou : Phase 1 obligatoire avant tout code custom.

---

## ADR-003 — Monorepo Git

**Statut** : Accepte le 2026-05-07

### Decision

Monorepo unique `formation-hub/` versionne ensemble :
- Compose files (`compose.yml`, overrides staging/prod)
- Bridge service (`bridge/`)
- Schemas Baserow (`baserow/schemas/`)
- Patches Docmost (`docmost/patches/`) si fork phase 2+
- Docs (`docs/`)
- CI/CD (`.github/workflows/`)

### Pourquoi

- Couplage fort entre infra, donnees, code custom — versionne ensemble = atomique
- Releases coordonnees (un tag = une version coherente du systeme)
- Un seul repo a cloner pour reproduire l'environnement

### Consequences

- Repo va grossir avec patches Docmost. Acceptable (pas de binaires lourds).
- CI/CD doit etre intelligent (ne build que ce qui a change).

---

## ADR-004 — Postgres separe Docmost / Baserow

**Statut** : Accepte le 2026-05-07

### Decision

Chaque service a son propre Postgres (deux containers) en local dev. Possibilite de partager une instance physique en prod via deux databases logiques si besoin perf.

### Pourquoi

- Isolation : un dump de Docmost n'affecte pas Baserow
- Versions Postgres potentiellement differentes selon les exigences
- Migration upstream de Docmost ou Baserow ne risque pas de casser l'autre

### Consequences

- Plus de RAM consommee (~200 Mo overhead par instance)
- Plus de complexite ops (deux backups distincts) — compense par scripts Makefile

---

## ADR-005 — Stack technique du bridge (Phase 2)

**Statut** : Provisoire — sera confirme avant Phase 2

### Hypothese

- **Runtime** : Node 22 LTS
- **Framework** : Hono (rapide, leger, TypeScript-first)
- **HTTP client** : ofetch ou native fetch
- **Cache** : Redis (memoire partagee avec Docmost ou dedie)
- **Validation** : zod
- **Tests** : vitest

### A confirmer en Phase 2

- Si on adopte Bun runtime au lieu de Node (perf + TS native)
- Si le bridge stocke un etat propre (Postgres dedie) ou reste stateless