home_stock/docs/adr/0002-architecture-monolithe-modulaire.md

ADR-0002 — Architecture monolithe modulaire

• Statut : accepted
• Date : 2026-01-27

---

Contexte

HomeStock nécessite une architecture logicielle adaptée à un projet mono-utilisateur self-hosted avec les contraintes suivantes :

• Simplicité de déploiement : L'application doit pouvoir être déployée facilement avec une seule commande
• Maintenance réduite : Pas d'équipe DevOps, maintenance manuelle par l'utilisateur
• Développement solo : Un seul développeur, besoin de cohérence et de simplicité
• Évolutivité future : Possibilité d'évoluer vers multi-utilisateurs sans refonte complète
• Modules logiques distincts : items, locations, categories, documents, search

Le projet démarre avec un périmètre limité (MVP) mais doit pouvoir évoluer progressivement. La question architecturale centrale est : comment organiser le code pour maximiser la maintenabilité tout en gardant une complexité opérationnelle minimale ?

---

Décision

Nous adoptons une architecture monolithe modulaire avec les caractéristiques suivantes :

Définition

• Un seul dépôt Git (monorepo) contenant backend et frontend
• Un seul processus backend (serveur FastAPI unique)
• Modules logiques séparés avec responsabilités clairement définies
• Communication intra-application via appels de fonctions directs
• Base de données unique partagée entre tous les modules

Organisation backend (backend/app/)

backend/app/
├── main.py                 # Point d'entrée FastAPI
├── core/                   # Configuration, logging, database
│   ├── config.py
│   ├── database.py
│   └── logging.py
├── models/                 # Modèles SQLAlchemy (un fichier par entité)
│   ├── item.py
│   ├── location.py
│   ├── category.py
│   └── document.py
├── schemas/                # Schémas Pydantic (validation API)
│   ├── item.py
│   ├── location.py
│   └── ...
├── routers/                # Endpoints API (un fichier par ressource)
│   ├── items.py
│   ├── locations.py
│   ├── categories.py
│   ├── documents.py
│   └── search.py
├── services/               # Logique métier (orchestration)
│   ├── item_service.py
│   ├── location_service.py
│   └── ...
├── repositories/           # Accès données (abstraction BDD)
│   ├── item_repository.py
│   ├── location_repository.py
│   └── ...
└── utils/                  # Utilitaires transverses
    ├── files.py
    └── search.py

Organisation frontend (frontend/src/)

frontend/src/
├── main.tsx               # Point d'entrée React
├── App.tsx                # Composant racine + routing
├── components/            # Composants réutilisables
│   ├── common/            # Boutons, inputs, modales...
│   ├── items/             # Composants spécifiques items
│   └── locations/         # Composants spécifiques locations
├── pages/                 # Pages complètes (routes)
│   ├── Dashboard.tsx
│   ├── ItemList.tsx
│   ├── ItemDetail.tsx
│   └── ...
├── hooks/                 # Custom hooks React
│   ├── useItems.ts
│   ├── useLocations.ts
│   └── ...
├── api/                   # Client API (fetch/axios)
│   ├── items.ts
│   ├── locations.ts
│   └── ...
└── utils/                 # Utilitaires helpers
    └── formatting.ts

Principes d'organisation

1. Séparation en couches backend : routers → services → repositories → models
2. Dépendances unidirectionnelles : Les couches supérieures dépendent des inférieures uniquement
3. Modules auto-contenus : Chaque module (items, locations, etc.) a ses propres fichiers dans chaque couche
4. Pas de dépendances circulaires entre modules
5. Code partagé dans core/ et utils/

---

Alternatives considérées

1. Microservices

Description : Séparer l'application en plusieurs services indépendants (service items, service locations, service search, etc.)

Avantages :

• ✅ Scalabilité horizontale indépendante par service
• ✅ Isolation des pannes (un service down ≠ tout down)
• ✅ Possibilité d'utiliser des technologies différentes par service
• ✅ Déploiement indépendant de chaque service

Inconvénients :

• ❌ Complexité opérationnelle énorme (orchestration, networking, monitoring)
• ❌ Nécessite API Gateway, service discovery, circuit breakers
• ❌ Communication réseau entre services (latence, sérialisations multiples)
• ❌ Transactions distribuées complexes (saga pattern)
• ❌ Debugging et traçabilité difficiles
• ❌ Overhead infrastructure (plusieurs conteneurs, load balancers, etc.)

Verdict : ❌ Rejeté - Complexité totalement disproportionnée pour un projet mono-utilisateur avec ~1 req/seconde max. Les bénéfices de scalabilité ne s'appliquent pas au cas d'usage.

2. Monolithe non structuré (big ball of mud)

Description : Tout le code dans quelques gros fichiers sans organisation claire

Avantages :

• ✅ Démarrage très rapide
• ✅ Pas de contraintes architecturales

Inconvénients :

• ❌ Maintenance cauchemardesque après quelques mois
• ❌ Code fortement couplé, difficile à tester
• ❌ Évolution impossible sans refonte complète
• ❌ Onboarding difficile pour contributeurs futurs

Verdict : ❌ Rejeté - Dette technique garantie, inacceptable même pour un projet solo

3. Architecture hexagonale (ports & adapters)

Description : Isolation stricte du domaine métier avec ports (interfaces) et adapters (implémentations)

Avantages :

• ✅ Isolation forte du domaine métier
• ✅ Testabilité maximale (mocks faciles)
• ✅ Changement de base de données transparent

Inconvénients :

• ❌ Boilerplate important (interfaces, adapters, DTOs multiples)
• ❌ Courbe d'apprentissage élevée
• ❌ Overhead pour un projet simple comme HomeStock

Verdict : ⚠️ Rejeté mais inspirant - Trop complexe pour notre besoin, mais on garde l'idée de séparation en couches (repository pattern)

4. Monolithe avec modules faiblement couplés (notre choix)

Description : Un seul déploiement avec modules logiques bien séparés et communication via interfaces claires

Avantages :

• ✅ Simplicité opérationnelle (un seul processus, un seul conteneur)
• ✅ Transactions ACID simples (même base de données)
• ✅ Pas de latence réseau entre modules
• ✅ Refactoring et debugging faciles
• ✅ Évolution progressive possible (extraction en microservices si vraiment nécessaire)
• ✅ Maintenance réduite

Inconvénients :

• ⚠️ Scalabilité horizontale limitée (non critique pour mono-utilisateur)
• ⚠️ Restart complet nécessaire pour tout changement (acceptable)

Verdict : ✅ Choisi - Meilleur équilibre complexité/bénéfices pour notre contexte

---

Conséquences

Positives

1. Déploiement simple : docker-compose up lance tout le système
2. Transactions ACID : Toutes les opérations en base profitent des transactions SQLite
3. Performance : Pas de latence réseau entre modules, appels de fonctions directs
4. Debugging facile : Stack traces complètes, un seul processus à inspecter
5. Refactoring sans risque : IDE et linters détectent les erreurs lors de renommages
6. Tests simples : Tests d'intégration faciles (toute l'app dans le même process)
7. Maintenance réduite : Un seul service à monitorer, logs centralisés naturellement

Négatives

1. Scalabilité limitée : Impossible de scaler un module indépendamment (non pertinent pour mono-utilisateur)
2. Couplage temporel : Si un module plante, tout plante (acceptable avec bonne gestion erreurs)
3. Restart complet : Modification = restart de toute l'app (dev avec hot-reload, prod peu de déploiements)

Mitigations

• Pour éviter le couplage fort : Respecter strictement les couches (routers → services → repositories)
• Pour faciliter évolution future : Interfaces claires entre modules, pas de dépendances circulaires
• Pour améliorer résilience : Gestion d'erreurs robuste, retry logic, circuit breaker patterns si nécessaire

---

Impacts techniques

Développement

• Pattern 3-layer : Chaque feature touche 3 fichiers minimum (router, service, repository)
• Imports Python : Imports absolus depuis app. pour éviter imports relatifs fragiles
• Tests : Tests unitaires par couche + tests d'intégration API end-to-end

Déploiement

• Docker : Un seul conteneur backend (+ conteneur frontend séparé pour SPA)
• Scaling : Scale vertical uniquement (augmenter CPU/RAM du conteneur)
• Rollback : Simple (redéploiement image Docker précédente)

Évolution future

Si le projet nécessite vraiment des microservices (multi-utilisateurs massif, équipes séparées) :

1. Extraction progressive : Modules déjà bien séparés, extraction facilitée
2. API interne → API externe : Appels de fonctions deviennent appels HTTP
3. Base partagée → bases séparées : Migrations Alembic facilitent séparation BDD

Cette architecture n'empêche pas l'évolution, elle la retarde jusqu'à ce qu'elle soit vraiment nécessaire (principe YAGNI = You Ain't Gonna Need It).

---

Notes

Cette décision s'inscrit dans la philosophie "Start with a monolith" popularisée par Martin Fowler et confirmée par de nombreux retours d'expérience (Shopify, GitHub, Stack Overflow ont démarré en monolithe).

Pour HomeStock, projet mono-utilisateur avec ~1 req/sec max en pic, un monolithe modulaire est largement suffisant et restera probablement optimal même à long terme.

La complexité des microservices n'apporterait aucun bénéfice tangible et augmenterait drastiquement les coûts de développement et maintenance.

Principe appliqué : "Choose boring technology" - privilégier les architectures éprouvées et simples sur les architectures à la mode mais complexes.

---

Contributeurs : Gilles (décideur) + Claude Code (architecte)

Références :

• Martin Fowler - "Monolith First" : https://martinfowler.com/bliki/MonolithFirst.html
• Sam Newman - "Building Microservices" (recommande de démarrer en monolithe)