home_stock/docs/adr/0001-choix-stack-technique.md

# ADR-0001 — Choix de la stack technique globale

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

---

## Contexte

HomeStock est une application web self-hosted de gestion d'inventaire domestique destinée à un usage mono-utilisateur. Les contraintes principales sont :

- **Simplicité de déploiement** : L'application doit être facile à installer et maintenir sur un réseau local
- **Usage mono-utilisateur** : Pas besoin de scalabilité horizontale ni de gestion complexe de concurrence
- **Self-hosted** : Déploiement local, pas de dépendance cloud
- **Développement rapide** : Besoin d'un MVP fonctionnel rapidement avec des technologies modernes et productives
- **Maintenance à long terme** : Stack stable avec un bon écosystème et une documentation solide

Le projet nécessite :
- Une API REST robuste pour le backend
- Une interface utilisateur moderne et réactive
- Une base de données adaptée au mono-utilisateur
- Un système de stockage de fichiers (photos, notices, factures)

---

## Décision

Nous avons choisi la stack technique suivante :

### Backend
- **Langage** : Python 3.11+
- **Framework API** : FastAPI
- **ORM** : SQLAlchemy 2.0+ avec Alembic pour migrations
- **Validation** : Pydantic (intégré à FastAPI)

### Frontend
- **Langage** : TypeScript
- **Framework UI** : React 18+
- **Bundler** : Vite 5+
- **Gestion état** : TanStack Query (React Query) pour l'état serveur, Context API pour l'état local
- **Styling** : TailwindCSS avec palette Gruvbox dark

### Base de données
- **SGBD** : SQLite avec extension FTS5 pour recherche full-text
- **Fichier** : `homestock.db` en local

### Stockage fichiers
- **Système** : Système de fichiers local
- **Organisation** : Dossier `uploads/` avec sous-dossiers par type (photos/, notices/, factures/)
- **Référencement** : Chemins relatifs stockés en base de données

### Déploiement
- **Conteneurisation** : Docker Compose
- **Réseau** : Réseau local 10.0.0.0/22

---

## Alternatives considérées

### Backend
1. **Django + Django REST Framework**
   - ✅ Framework très complet avec admin intégré
   - ✅ ORM mature et puissant
   - ❌ Plus lourd et verbeux que FastAPI
   - ❌ Performance inférieure en async
   - **Rejeté** : Trop de fonctionnalités inutiles pour notre cas d'usage mono-utilisateur

2. **Go avec Gin/Echo**
   - ✅ Très performant, binaire standalone
   - ✅ Faible consommation mémoire
   - ❌ Écosystème moins riche pour gestion fichiers/images
   - ❌ Développement plus verbeux, moins rapide
   - **Rejeté** : Performance non critique pour mono-utilisateur, productivité Python préférée

3. **Node.js avec Express/Fastify**
   - ✅ Écosystème npm très riche
   - ✅ Même langage que le frontend (JavaScript/TypeScript)
   - ❌ Gestion async plus complexe qu'avec FastAPI
   - ❌ Préférence personnelle pour Python
   - **Rejeté** : Moins d'expérience, Python préféré pour backend

### Frontend
1. **Vue.js 3**
   - ✅ Simple à apprendre, Composition API moderne
   - ✅ Excellente documentation
   - ❌ Écosystème légèrement moins riche que React
   - **Rejeté** : React préféré pour son écosystème et l'expérience existante

2. **Svelte/SvelteKit**
   - ✅ Très léger, compilation au build
   - ✅ Syntaxe simple et élégante
   - ❌ Écosystème moins mature
   - ❌ Moins de ressources et bibliothèques tierces
   - **Rejeté** : Écosystème trop jeune pour un projet à long terme

### Base de données
1. **PostgreSQL**
   - ✅ Très robuste, fonctionnalités avancées
   - ✅ Meilleure recherche full-text (GIN indexes)
   - ❌ Serveur séparé à gérer, plus complexe
   - ❌ Overhead pour mono-utilisateur avec faible volume
   - **Rejeté** : Trop complexe pour un usage mono-utilisateur avec <10k items attendus

2. **MySQL/MariaDB**
   - ✅ Populaire, bien documenté
   - ✅ Bonnes performances
   - ❌ Recherche full-text moins performante
   - ❌ Serveur séparé à gérer
   - **Rejeté** : Même raison que PostgreSQL, SQLite suffit largement

### Stockage fichiers
1. **MinIO (S3-compatible)**
   - ✅ Scalable, versioning, métadonnées riches
   - ✅ Compatible S3, facilite migration future
   - ❌ Service supplémentaire à déployer et maintenir
   - ❌ Overhead pour mono-utilisateur
   - **Rejeté** : Trop complexe pour le besoin, système fichiers local suffit

2. **Stockage en base (BLOB)**
   - ✅ Pas de fichiers externes à gérer
   - ✅ Transactions ACID sur fichiers
   - ❌ Performance dégradée avec fichiers volumineux
   - ❌ Backup et restauration plus complexes
   - ❌ Taille de la base de données augmente rapidement
   - **Rejeté** : Mauvaise pratique, problèmes de performance prévisibles

---

## Conséquences

### Positives
1. **Simplicité de déploiement** : Un seul `docker-compose up` lance l'ensemble de la stack
2. **Performance suffisante** : FastAPI async + SQLite suffisent largement pour mono-utilisateur
3. **Développement rapide** : FastAPI + React offrent une excellente productivité
4. **Pas de serveur BDD externe** : SQLite embarqué, un seul fichier à sauvegarder
5. **Auto-documentation API** : FastAPI génère automatiquement OpenAPI/Swagger
6. **Typage fort** : TypeScript (frontend) + Pydantic (backend) réduisent les erreurs
7. **Écosystèmes matures** : Python et React ont d'excellentes bibliothèques tierces
8. **Recherche performante** : FTS5 SQLite offre une recherche full-text native et rapide

### Négatives
1. **Limitations SQLite** : Pas de scalabilité horizontale (non critique pour mono-utilisateur)
2. **Recherche limitée** : FTS5 moins puissant qu'Elasticsearch (acceptable pour <10k items)
3. **Stockage fichiers manuel** : Pas de métadonnées avancées ni versioning
4. **Backup manuel** : Nécessite scripts de backup pour fichiers + BDD
5. **Migration future** : Si passage multi-utilisateurs, migration vers PostgreSQL nécessaire

### Neutres
1. **Deux langages** : Python (backend) + TypeScript (frontend) nécessitent deux environnements
2. **Complexité initiale React** : Courbe d'apprentissage pour développement React moderne

---

## Impacts techniques

### Organisation du code
- **Monorepo** : Backend et frontend dans le même dépôt
- **Structure backend** : `backend/app/` avec routers/, models/, schemas/, services/, repositories/
- **Structure frontend** : `frontend/src/` avec components/, pages/, hooks/, api/

### Dépendances principales
- **Backend** : fastapi, uvicorn, sqlalchemy, alembic, pydantic, python-multipart, loguru
- **Frontend** : react, react-router-dom, @tanstack/react-query, tailwindcss, axios

### Développement
- **Tests** : pytest (backend), vitest (frontend)
- **Lint/Format** : ruff + mypy (backend), eslint + prettier (frontend)
- **CI/CD** : Gitea Actions avec lint → test → build → deploy

### Déploiement
- **Docker** : 3 services (backend, frontend, reverse proxy optionnel)
- **Volumes** : Persistance pour `homestock.db` et `uploads/`
- **Ports** : Backend :8000, Frontend :5173 (dev) ou :80/:443 (prod avec reverse proxy)

### Évolutivité future
- **Migration PostgreSQL** : Possible via Alembic migrations si besoin
- **Stockage S3** : Abstraction stockage permet ajout MinIO sans refonte
- **Multi-utilisateurs** : Architecture modulaire facilite ajout authentification/RBAC

---

## Notes

Cette stack a été choisie en janvier 2026 pour un MVP mono-utilisateur. Les choix privilégient la simplicité et la rapidité de développement sur la scalabilité et les fonctionnalités avancées qui ne sont pas nécessaires pour le cas d'usage initial.

La stack permet une évolution progressive vers multi-utilisateurs et stockage cloud si besoin, mais ces aspects sont volontairement exclus du MVP pour réduire la complexité initiale.

Les alternatives (PostgreSQL, MinIO) restent envisageables pour des évolutions futures et sont documentées dans la section "Améliorations prévues" de [docs/ARCHITECTURE.md](../ARCHITECTURE.md).

---

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