home_stock/docs/ARCHITECTURE.md

Architecture du projet

Ce document formalise l’architecture cible. Il doit être maintenu à jour. Il sert de base aux décisions techniques, aux ADR et au découpage des tâches.

---

Légende des zones

• <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer) : à compléter par toi selon le projet.
• <A COMPLETER PAR AGENT> : à compléter par un agent spécialisé architecture.

---

1. Vue d'ensemble

• Objectif produit : Gérer l'inventaire complet d'un domicile avec recherche, localisation précise et archivage de documents
• Type d'app : Application web full-stack (API REST + SPA) avec déploiement conteneurisé
• Contraintes fortes : Self-hosted sur réseau local, mono-utilisateur, simplicité de déploiement et maintenance

2. Principes d'architecture

• Principes non négociables : Monolithe modulaire, séparation stricte frontend/backend, documentation avant implémentation, ADR pour décisions structurantes
• Principes d'évolution : Architecture permettant une évolution vers multi-utilisateurs sans refonte complète, modules indépendants testables séparément
• Qualités prioritaires : Simplicité d'utilisation > Performance > Maintenabilité > Évolutivité (mono-utilisateur donc pas de scalabilité horizontale)

3. Architecture logique

• Modules principaux : items (objets/équipements), locations (emplacements physiques), categories (domaines: bricolage, informatique, etc.), documents (photos, notices, factures), search (recherche full-text)
• Responsabilités par module : items = CRUD objets + état + prix, locations = hiérarchie lieux (meuble>tiroir>boîte), categories = classification, documents = upload/stockage fichiers, search = indexation et recherche
• Frontend/Backend séparation : SPA React (frontend) communique uniquement via API REST avec FastAPI (backend), pas de SSR (Server-Side Rendering), API documentée par OpenAPI

4. Architecture technique

• Langages & frameworks : Backend = Python 3.11+ avec FastAPI + SQLAlchemy + Pydantic, Frontend = TypeScript + React 18+ + Vite + TailwindCSS
• Base de données : SQLite (fichier local homestock.db) avec FTS5 pour recherche full-text, migrations via Alembic
• Stockage fichiers : Système de fichiers local, dossier uploads/ organisé par type (photos/, notices/, factures/), chemin relatif stocké en BDD
• Infra cible : Self-hosted via Docker Compose, réseau local 10.0.0.0/22, reverse proxy optionnel (Traefik/Nginx)

5. Flux de données

• Flux principaux : Lecture = GET items avec filtres (catégorie, localisation, état) + recherche full-text, Écriture = POST/PUT/DELETE items + upload fichiers multipart/form-data
• Intégrations externes : Aucune intégration externe prévue, système autonome et déconnecté
• Gestion des événements/asynchronisme : Upload fichiers en asynchrone (FastAPI background tasks), pas d'événements temps réel pour MVP (possibilité WebSocket future)

6. Sécurité

• Authentification/autorisation : Optionnelle pour MVP mono-utilisateur, si activée = login simple (username/password) + session cookie, pas de JWT pour simplicité
• Données sensibles : Factures (montants, dates d'achat), localisations précises d'objets de valeur → chiffrement au repos optionnel, accès réseau local uniquement
• Traçabilité/audit : Pas d'audit trail strict pour MVP, timestamps created_at/updated_at sur entités principales, logs applicatifs pour debug

7. Observabilité

• Logs : Python logging avec rotation (loguru recommandé), niveau INFO en production, DEBUG en dev, format JSON pour parsing
• Metrics : Optionnelles pour MVP, possibilité ajout Prometheus + Grafana plus tard (nb items, espace disque uploads/, temps réponse API)
• Alerting : Pas d'alerting pour MVP mono-utilisateur, monitoring manuel via logs et health check endpoint /health

8. Conventions de code

• Organisation des dossiers : Backend = backend/app/ (routers/, models/, schemas/, services/), Frontend = frontend/src/ (components/, pages/, hooks/, api/)
• Standards de code : Backend = ruff format + mypy strict, Frontend = ESLint + Prettier, nommage snake_case (Python) et camelCase (TS), français pour commentaires
• Tests obligatoires : Backend = tests unitaires (services/) + tests intégration (API), Frontend = tests unitaires (utils/hooks), couverture minimum 70% sur logique métier

9. Évolution & dette

• Zones à risque : Recherche full-text sur SQLite (limitations si >10k items), stockage fichiers local (backup manuel nécessaire), authentification simpliste
• Améliorations prévues : Migration SQLite→PostgreSQL si besoin, stockage fichiers vers MinIO/S3, multi-utilisateurs avec RBAC (contrôle d'accès par rôle), API mobile, import/export CSV

---