Wiki/docs/04-cahier-des-charges-techniques.md

Cahier des Charges Techniques (CDC)

Specification technique complete : stack, choix, contraintes, NFR, architecture, roadmap. Version : 1.0 — Date : 2026-05-07. Statut : draft, a valider Yan/Ludo avant industrialisation.

1. Identification

Champ	Valeur
Nom du projet	formation-hub
Owner technique	Corentin JOGUET (DevOps/AdminSys, bras droit Yan)
Validateurs	Yan (resp tech), Ludo (direction)
Sponsor metier	Direction Acadenice
Type	Outil interne — Notion-like self-host pour CFA + Agence dev
Date debut	2026-05-07
Date cible MVP	T+1 mois (Phase 1 — stack vanilla + setup metier)
Date cible v1.0	T+3 mois (Phase 2 — bridge UX unifie)

2. Contexte metier

Acadenice = double activite CFA + Agence dev (cf doc fondateur "Vision Acadenice"). Les formateurs sont aussi developpeurs sur projets clients : leur capacite annuelle se split entre les deux activites.

Le projet formation-hub fournit l'outil interne pour :

• Wiki collaboratif (SOPs, supports, doc technique)
• Suivi heures formation (CFA)
• Suivi projets et taches Agence
• Vue 360 capacite par personne (formation + agence)
• Acces guests clients (lien partage)
• Spaces personnels etudiants (libres, non modelises)

3. Objectifs

Objectif	Mesure
Centraliser la documentation	100% des SOPs et supports formation dans l'outil
Tracer les heures formateurs	Saisie reguliere par 100% des formateurs
Tracer les heures projets clients	Saisie reguliere par 100% des devs
Calcul automatique heures restantes	Tableau de bord temps reel par formation, par formateur, par projet
Reduire le couplage outils externes	Remplacer 0 a 3 outils actuels (Excel, Trello legers ?)
Self-host illimite users	Aucun cout de licence par seat, juste l'infra
Ouvert aux etudiants	Spaces personnels libres, beneficient des templates

4. Perimetre fonctionnel

Couvert :

• Wiki Docmost avec mermaid/drawio/excalidraw natifs
• Bases de donnees Baserow (CFA + Agence)
• Permissions hierarchiques (workspace, space, page)
• Share links avec password / expiration
• Acces guests clients

Non couvert (out of scope v1) :

• Modelisation formelle des etudiants (inscriptions, suivi pedagogique)
• Generation factures clients
• ATS / recrutement
• Messagerie integree
• Application mobile native (UI mobile-friendly via responsive web)

5. Stack technique

5.1 Diagramme architecture cible

flowchart TB
    User([Utilisateur final<br/>Admin/Formateur/Dev/Etudiant/Client])

    subgraph "Edge / Reverse Proxy"
        Traefik[Traefik<br/>TLS Let's Encrypt<br/>routing par sous-domaine]
    end

    User -->|HTTPS| Traefik
    Traefik -->|wiki.acadenice.fr| Docmost
    Traefik -->|baserow.acadenice.fr| Baserow
    Traefik -->|bridge.acadenice.fr| Bridge

    subgraph "Application services"
        Docmost[Docmost<br/>NestJS + React + Tiptap]
        Baserow[Baserow<br/>Django + Caddy interne]
        Bridge[Bridge service<br/>Node 22 + Hono<br/>Phase 2]
    end

    subgraph "Storage"
        DocmostDB[(Postgres<br/>docmost)]
        DocmostRedis[(Redis<br/>docmost)]
        BaserowDB[(Postgres<br/>baserow embedded)]
        BaserowRedis[(Redis<br/>baserow embedded)]
        FS[Local FS / MinIO<br/>docmost files]
    end

    Docmost --> DocmostDB
    Docmost --> DocmostRedis
    Docmost --> FS
    Baserow --> BaserowDB
    Baserow --> BaserowRedis
    Bridge -->|API REST| Baserow
    Bridge --> DocmostRedis
    Bridge -->|API REST| Docmost

    subgraph "Infra ops"
        CronBackup[Cron host<br/>backups quotidiens]
        Monitoring[Uptime monitoring<br/>a definir]
    end

    CronBackup -->|pg_dump + tar| DocmostDB
    CronBackup -->|pg_dump + tar| BaserowDB
    CronBackup -->|tar| FS

5.2 Composants

Composant	Role	Techno	Version cible	License
Docmost	Wiki + collab + share + diagrammes natifs	NestJS, React, Tiptap, Postgres	latest stable (>= v0.8.2 mai 2026)	AGPL-3.0
Baserow	DBs structurees + multi-vues + rollups + formules	Django, Postgres, Redis, Celery, Caddy	1.30.x pinned	MIT (core)
Bridge (Phase 2)	API entre Docmost (Tiptap nodes custom) et Baserow	Node 22, Hono, zod, ofetch	1.0 (a developper)	MIT (interne)
PostgreSQL	DB pour Docmost + DB pour Baserow (containers separes)	Postgres 16 alpine	16.x	PostgreSQL License
Redis	Cache et queues (Docmost + Bridge)	Redis 7 alpine	7.x	RSAL (free pour notre usage)
MinIO ou local FS	Storage attachments Docmost	MinIO	latest stable	AGPL-3.0
Traefik	Reverse proxy, TLS auto	Traefik 3.x (deja deploye)	latest	MIT
Docker / Compose	Containerisation, orchestration	Docker 25+, compose v2	latest	Apache 2.0
GitHub Actions	CI/CD	GitHub Actions	—	—

5.3 Versions pinning

• Docmost : docmost/docmost:latest initialement, pinned sur version mineure stable apres tests (ex: v0.8.2)
• Baserow : baserow/baserow:1.30.1 (deja pinne)
• Postgres : postgres:16-alpine
• Redis : redis:7-alpine
• Node Bridge : node:22-alpine
• Bumps version : decision manuelle apres test staging

6. Choix de stack — justifications

Choix	Alternatives ecartees	Raison
Docmost comme wiki	AFFiNE (10-seat limit), AppFlowy (1-user limit), Outline (BSL + pas de bidirec), SiYuan/Trilium (single-user), HedgeDoc (pas de DB ni bidirec)	Seul wiki AGPL avec users illimites, team workspaces, share links et diagrammes natifs (Mermaid + Draw.io + Excalidraw) integres
Baserow comme moteur DB	NocoDB (license non-OSI Sustainable Use), Teable (jeune, pas mature), Airtable (cloud paye), construire un moteur DB dans Docmost (4-6 mois)	MIT, mature, real-time collab, rollups+formules natifs, multi-vues completes, users illimites
Stack composite vs unifie	AFFiNE Team paid (~2200€/an) ou tout custom	Zero recurrent + Stack mainstream + decouple = remplaceable
Bridge custom Node TS	Embed iframe Baserow ou reecrire UI complete	UX unifie sans Tiptap reverse engineering Docmost. Effort 2-3 mois acceptable.
Postgres separe par service	Postgres partage avec 2 databases	Isolation versions, migrations independantes, dump/restore propres
Hono pour le bridge	Express, Fastify, NestJS, Bun	Leger, TypeScript-first, performance Edge-ready, simple a deployer
Path B (UX quasi-unified) vs Path A (deux mondes)	Cross-link URL externe entre Docmost et Baserow	UX unifie evite jonglage 2 onglets pour les utilisateurs

(Voir 02-decision-record.md pour les ADR detailles.)

7. Specifications non-fonctionnelles (NFR)

7.1 Performance

Metrique	Cible	Mesure
Latence saisie heures (UC-13, UCA-07)	< 2s p95	Bridge endpoint timing
Latence chargement page wiki	< 1s p95	Lighthouse
Recalcul rollups Baserow	< 5s	Baserow-side timing
Recherche full-text Docmost	< 500ms p95	Docmost search timing

7.2 Securite

Aspect	Specification
Auth Docmost	Email + password, SSO OIDC en option (Phase 3)
Auth Baserow	Email + password, JWT
Auth Bridge	API tokens longue duree pour service-to-service
TLS	Let's Encrypt via Traefik, renouvellement auto
Backup encryption	AES-256 sur backups distants (MinIO/S3 distant)
Secrets	Variables d'environnement docker-compose, fichier .env exclu de git
Audit log	Log toutes operations sensibles (suppression, archivage, partage externe)
RGPD	Suppression de donnees personnelles sur demande, retention etudiants/clients selon loi

7.3 Disponibilite

Aspect	Cible	Justification
Disponibilite stack	99% (= 3.65j down/an)	Outil interne, pas critique
RPO (Recovery Point Objective)	24h max	Backup quotidien
RTO (Recovery Time Objective)	4h max	Restauration manuelle assistee
MTTR	< 1h pour bugs critiques, < 24h pour bugs mineurs	Bug critique = bloquant pour une activite

7.4 Scalabilite

Cible v1 : ~30 users simultanes peak, 100 users total — hors-perf sur un VPS 4 vCPU/8 Go.

Croissance an 5 prevue : ~150 users total, ~50 simultanes peak. Pas de refactor stack prevu — juste un upsizing VPS si besoin.

7.5 Backup / Disaster recovery

Aspect	Strategie
Frequence	Quotidienne, 03:00 UTC
Targets	Postgres docmost (pg_dump.gz), Postgres baserow embedded (pg_dump.gz), Docmost FS (tar.gz), Baserow data (tar.gz)
Retention	30 jours sur disque local, 90 jours sur stockage distant (S3 / Backblaze)
Test restauration	Mensuel, sur un environnement test isole
RPO	24h
RTO	4h

8. Contraintes

Contrainte	Justification
Self-host obligatoire	Souverainete des donnees, pas de SaaS payant
Stack OSS (AGPL/MIT/Apache acceptable)	Eviter lock-in vendor
Docker + Compose	Stack ops existante d'Acadenice
Traefik reverse proxy	Stack ops existante (labels TOML)
GitHub pour le code	Workflow standard equipe
Budget recurrent : 0 (hors infra ~30€/mois)	Decision direction
Equipe dev : Corentin solo + freelance ponctuel pour Tiptap	Pas d'embauche dediee

9. Hypotheses / dependances

• Le hardware serveur (VPS Hetzner ou equivalent) est commande / disponible avant deploiement staging
• Un nom de domaine acadenice.com ou acadenice.fr est disponible pour les sous-domaines wiki/baserow/bridge
• Traefik tourne deja en prod chez Acadenice — on s'integre dans le reseau Docker existant
• L'API Outline reste accessible pendant la phase de validation (push docs depuis local pour relecture)
• Docmost et Baserow continuent d'etre maintenus activement par leur upstream pendant la duree du projet

10. Risques et mitigations

Risque	Probabilite	Impact	Mitigation
Docmost upstream change ses API publiques	Faible	Moyen	Pinning de versions, tests staging avant bump
Baserow change son data model en breaking	Moyenne	Eleve	Backups frequents, migration test avant bump
Tiptap node-views complexe pour AdminSys solo	Eleve	Moyen	Freelance senior fullstack TS pour 2-3 jours pair-programming
AGPL conformite (publication code source si SaaS public)	Faible	Eleve	Outil reste interne — pas SaaS public, AGPL OK
Charge depasse capacite VPS 4 vCPU	Faible	Moyen	Upsizing simple, cloud-native
Perte de cle API Outline ou Baserow	Faible	Faible	Rotation manuelle simple, secrets dans .env
Manque adoption metier (saisie heures non faite)	Moyenne	Eleve	Onboarding etalonne + UX simple + relances admin

11. Roadmap technique

Phase 0 — Conception (en cours, fini fin mai)

• Discovery + decisions
• Data dictionary, MCD, MLD, UML use cases, state diagrams, MCT, MOT, class diagram, activity diagrams
• CDC technique (ce doc)
• MPD Baserow (table-par-table)
• Validation metier (Yan + Ludo + admin pedagogique)

Phase 1 — MVP vanilla (T+1 mois)

• Setup stack Docker compose locale → staging
• Configuration Docmost (workspace, spaces, share links)
• Configuration Baserow (4 BDDs CFA + 4 BDDs Agence)
• Migration data initiale (formations existantes, formateurs, clients, projets en cours)
• Onboarding 5-10 power users
• Backup + monitoring de base

Phase 2 — Bridge UX unifie (T+3 mois)

• Bridge service skeleton + premier Tiptap node-view custom (mention @formateur, @projet)
• Routes /personne/:id, /projet/:id, /formation/:id en page Docmost-style
• Saisie heures formateur + intervention dev en bridge UI mobile-friendly
• Webhook Baserow → bridge → cache Redis pour mentions
• Migration progressive utilisateurs (formateurs + devs ouvrent le bridge plutot que Baserow direct)

Phase 3 — Maturite (T+6 mois)

• Bidirec backlinks dans Docmost (custom)
• Workflow approbation heures realisees (review admin)
• Notifications avancees (Slack/Teams)
• Rapports PDF (formation + formateur + projet)
• SSO OIDC pour gros volume users

Phase 4 — Optimisation & extensions (T+9 mois)

• Modelisation etudiants si besoin metier
• Integration calendrier (iCal export)
• API publique limitee pour clients (auto-service projets)
• Multi-langue UI (EN en plus de FR)

12. Estimations couts

Infra (recurrent)

Element	Cout
VPS Hetzner CPX31 ou CCX23 (4 vCPU/8 Go)	13-30€/mois
Stockage backup distant (Backblaze B2 / OVH Object Storage)	5-10€/mois
Domaine + sous-domaines	15€/an
Total recurrent	~30€/mois = ~360€/an

Dev (one-shot)

Phase	Effort	Cout estime
Phase 0 — Conception	~10h Corentin	Inclus salaire
Phase 1 — MVP vanilla	~80h Corentin	Inclus salaire
Phase 2 — Bridge	~200-300h Corentin + 2-3j freelance Tiptap	Salaire + ~2k€ freelance
Phase 3 — Maturite	~150h Corentin	Inclus salaire
Total externe		~2-3k€ (freelance ponctuel)

13. Glossaire

Terme	Definition
CFA	Centre de Formation des Apprentis
RNCP	Repertoire National des Certifications Professionnelles (les blocs de competences)
Bloc de competences	Ensemble homogene et coherent de competences validees ensemble
Module	Lecon individuelle au sein d'un bloc
Attribution	Affectation d'un module a un formateur avec heures
Intervention	Travail d'un developpeur sur une tache projet client (avec heures)
Formation pedagogique	Cas ou un projet client sert de support de formation pour des etudiants
Bridge	Service intermediaire qu'on construit entre Docmost et Baserow
Tiptap	Editor framework utilise par Docmost (extension de ProseMirror)
Node-view	Composant React custom integre dans un editeur Tiptap
Rollup	Calcul d'agregation Baserow (sum, count, avg) sur une relation
Path A / Path B	Strategies d'integration Docmost-Baserow (cf ADR-002)

14. References

• Doc fondateur Vision Acadenice : KxvipVcxNV
• Discovery recap : 01-discovery-recap.md
• Decision records : 02-decision-record.md
• Data dictionary : 05-data-dictionary.md
• MCD : 06-merise-mcd.md
• MLD : 07-merise-mld.md
• Sources externes verifiees :
  • Docmost AGPL pricing
  • Docmost v0.3.0 release Mermaid+Drawio+Excalidraw
  • AFFiNE 10-seat limit
  • AppFlowy 1-user limit
  • Baserow vs NocoDB comparison