Initial commit

docs/adr/016-organisation-monorepo.md

@@ -0,0 +1,87 @@
+# ADR-016 : Organisation en Monorepo
+
+**Statut** : Accepté
+**Date** : 2025-01-24
+
+## Contexte
+
+RoadWave comprend plusieurs composants (backend Go, mobile React Native/Flutter, documentation, tests BDD). Il faut décider de l'organisation des repositories : monorepo unique, multirepo avec submodules, ou repos totalement séparés.
+
+Les tests Gherkin existants décrivent des **fonctionnalités bout-en-bout** (front + mobile + back) et doivent rester cohérents entre tous les composants.
+
+## Décision
+
+**Monorepo unique** contenant backend, mobile, documentation et features Gherkin.
+
+## Alternatives considérées
+
+| Option | Cohérence | Complexité | Onboarding | Déploiements |
+|--------|-----------|------------|------------|--------------|
+| **Monorepo** | Excellente | Faible | Simple (1 clone) | Couplés |
+| Multirepo + submodules | Moyenne | Élevée | Complexe | Indépendants |
+| Multirepo séparés | Faible | Moyenne | Moyen | Indépendants |
+
+## Justification
+
+- **Source de vérité unique** : documentation et Gherkin partagés, pas de désynchronisation
+- **Versionning cohérent** : un tag Git = release complète front + back compatible
+- **Tests e2e simplifiés** : tout le code disponible localement pour tests intégrés
+- **Expérience développeur** : un seul `git clone`, historique unifié, changements cross-stack facilités
+- **Stade du projet** : début de projet où agilité et changements rapides sont critiques
+
+## Structure
+
+```
+roadwave/
+├── docs/                          # Documentation commune (ADR, règles métier)
+├── features/                      # Tests BDD Gherkin partagés
+│   ├── authentication/
+│   ├── navigation/
+│   └── ...
+├── backend/                       # Application Go
+│   ├── cmd/
+│   ├── internal/
+│   ├── pkg/
+│   ├── migrations/
+│   ├── tests/
+│   │   └── bdd/                   # Step definitions Go (API)
+│   └── go.mod
+├── mobile/                        # Application React Native/Flutter
+│   ├── src/
+│   ├── tests/
+│   │   └── bdd/                   # Step definitions mobile (UI)
+│   └── package.json / pubspec.yaml
+├── shared/                        # Code partagé (types, contrats API)
+├── docker-compose.yml             # Stack complète locale
+└── Makefile                       # Commandes communes
+```
+
+## Gestion des tests Gherkin
+
+**Principe** : Les fichiers `.feature` restent **partagés** dans `/features`, mais chaque projet implémente ses **step definitions**.
+
+```
+features/authentication/inscription.feature    → Scénario fonctionnel
+
+backend/tests/bdd/inscription_steps.go         → Teste l'API
+mobile/tests/bdd/inscription_steps.dart        → Teste l'UI mobile
+```
+
+Cela garantit que :
+- Les spécifications métier sont uniques et cohérentes
+- Chaque couche teste sa responsabilité
+- Les tests valident le contrat entre front et back
+
+## Outillage
+
+- **Turborepo** ou **Nx** : orchestration des builds/tests, cache intelligent
+- **Docker Compose** : environnement de dev local (PostgreSQL, Redis, backend, etc.)
+- **Make** : commandes communes (`make test`, `make build`, `make dev`)
+- **CI/CD** : GitHub Actions avec path filters (rebuild seulement ce qui change)
+
+## Conséquences
+
+- **Positif** : cohérence maximale, onboarding simplifié, changements cross-stack facilités
+- **Négatif** : repo plus volumineux, nécessite CI intelligente pour éviter builds lents
+- **Migration future** : si le monorepo devient ingérable (>100k LOC), split possible mais improbable à moyen terme
+- **Permissions** : tout le monde voit tout (transparence encouragée en phase startup)