claude code

docs/ARCHITECTURE.md

@@ -11,54 +11,49 @@ Il sert de base aux décisions techniques, aux ADR et au découpage des tâches.
 
 ---
 
-## 1. Vue d’ensemble
-- Objectif produit : <A REMPLIR - PROJET> (exemple: améliorer la traçabilité — a supprimer)
-- Type d’app (web, mobile, API) : <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer)
-- Contraintes fortes : <A REMPLIR - PROJET> (exemple: déploiement on-premise — a supprimer)
+## 1. Vue d'ensemble
+- Objectif produit : Gérer l'inventaire complet d'un domicile avec recherche, localisation précise et archivage de documents <!-- complété par codex -->
+- Type d'app : Application web full-stack (API REST + SPA) avec déploiement conteneurisé <!-- complété par codex -->
+- Contraintes fortes : Self-hosted sur réseau local, mono-utilisateur, simplicité de déploiement et maintenance <!-- complété par codex -->
 
-## 2. Principes d’architecture
-- Principes non négociables : <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer)
-- Principes d’évolution : <A COMPLETER PAR AGENT>
-- Qualités prioritaires (performance, sécurité, scalabilité) : <A REMPLIR - PROJET> (exemple: sécurité et performance — a supprimer)
+## 2. Principes d'architecture
+- Principes non négociables : Monolithe modulaire, séparation stricte frontend/backend, documentation avant implémentation, ADR pour décisions structurantes <!-- complété par codex -->
+- Principes d'évolution : Architecture permettant une évolution vers multi-utilisateurs sans refonte complète, modules indépendants testables séparément <!-- complété par codex -->
+- Qualités prioritaires : Simplicité d'utilisation > Performance > Maintenabilité > Évolutivité (mono-utilisateur donc pas de scalabilité horizontale) <!-- complété par codex -->
 
 ## 3. Architecture logique
-- Modules principaux : <A COMPLETER PAR AGENT>
-- Responsabilités par module : <A COMPLETER PAR AGENT>
-- Frontend/Backend séparation : <A COMPLETER PAR AGENT>
+- Modules principaux : `items` (objets/équipements), `locations` (emplacements physiques), `categories` (domaines: bricolage, informatique, etc.), `documents` (photos, notices, factures), `search` (recherche full-text) <!-- complété par codex -->
+- 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 <!-- complété par codex -->
+- 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 <!-- complété par codex -->
 
 ## 4. Architecture technique
-- Langages & frameworks : <A COMPLETER PAR AGENT>
-- Base de données : <A COMPLETER PAR AGENT>
-- Stockage fichiers : <A COMPLETER PAR AGENT>
-- Infra cible (cloud/self-hosted) : <A REMPLIR - PROJET> (exemple: self-hosted — a supprimer)
+- Langages & frameworks : Backend = Python 3.11+ avec FastAPI + SQLAlchemy + Pydantic, Frontend = TypeScript + React 18+ + Vite + TailwindCSS <!-- complété par codex -->
+- Base de données : SQLite (fichier local homestock.db) avec FTS5 pour recherche full-text, migrations via Alembic <!-- complété par codex -->
+- Stockage fichiers : Système de fichiers local, dossier `uploads/` organisé par type (photos/, notices/, factures/), chemin relatif stocké en BDD <!-- complété par codex -->
+- Infra cible : Self-hosted via Docker Compose, réseau local 10.0.0.0/22, reverse proxy optionnel (Traefik/Nginx) <!-- complété par codex -->
 
 ## 5. Flux de données
-- Flux principaux (lecture/écriture) : <A COMPLETER PAR AGENT>
-- Intégrations externes : <A REMPLIR - PROJET> (exemple: ERP existant — a supprimer)
-- Gestion des événements/asynchronisme : <A COMPLETER PAR AGENT>
+- Flux principaux : Lecture = GET items avec filtres (catégorie, localisation, état) + recherche full-text, Écriture = POST/PUT/DELETE items + upload fichiers multipart/form-data <!-- complété par codex -->
+- Intégrations externes : Aucune intégration externe prévue, système autonome et déconnecté <!-- complété par codex -->
+- Gestion des événements/asynchronisme : Upload fichiers en asynchrone (FastAPI background tasks), pas d'événements temps réel pour MVP (possibilité WebSocket future) <!-- complété par codex -->
 
 ## 6. Sécurité
-- Authentification/autorisation : <A COMPLETER PAR AGENT>
-- Données sensibles : <A REMPLIR - PROJET> (exemple: emails + historiques de paiement — a supprimer)
-- Traçabilité/audit : <A COMPLETER PAR AGENT>
+- Authentification/autorisation : Optionnelle pour MVP mono-utilisateur, si activée = login simple (username/password) + session cookie, pas de JWT pour simplicité <!-- complété par codex -->
+- 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 <!-- complété par codex -->
+- Traçabilité/audit : Pas d'audit trail strict pour MVP, timestamps created_at/updated_at sur entités principales, logs applicatifs pour debug <!-- complété par codex -->
 
 ## 7. Observabilité
-- Logs (journaux) : <A COMPLETER PAR AGENT>
-- Metrics (mesures) : <A COMPLETER PAR AGENT>
-- Alerting (alertes) : <A COMPLETER PAR AGENT>
+- Logs : Python logging avec rotation (loguru recommandé), niveau INFO en production, DEBUG en dev, format JSON pour parsing <!-- complété par codex -->
+- Metrics : Optionnelles pour MVP, possibilité ajout Prometheus + Grafana plus tard (nb items, espace disque uploads/, temps réponse API) <!-- complété par codex -->
+- Alerting : Pas d'alerting pour MVP mono-utilisateur, monitoring manuel via logs et health check endpoint `/health` <!-- complété par codex -->
 
 ## 8. Conventions de code
-- Organisation des dossiers : <A COMPLETER PAR AGENT>
-- Standards de code : <A COMPLETER PAR AGENT>
-- Tests obligatoires : <A COMPLETER PAR AGENT>
+- Organisation des dossiers : Backend = `backend/app/` (routers/, models/, schemas/, services/), Frontend = `frontend/src/` (components/, pages/, hooks/, api/) <!-- complété par codex -->
+- Standards de code : Backend = ruff format + mypy strict, Frontend = ESLint + Prettier, nommage snake_case (Python) et camelCase (TS), français pour commentaires <!-- complété par codex -->
+- Tests obligatoires : Backend = tests unitaires (services/) + tests intégration (API), Frontend = tests unitaires (utils/hooks), couverture minimum 70% sur logique métier <!-- complété par codex -->
 
 ## 9. Évolution & dette
-- Zones à risque : <A REMPLIR - PROJET> (exemple: montée en charge — a supprimer)
-- Améliorations prévues : <A REMPLIR - PROJET> (exemple: reporting avancé — a supprimer)
+- Zones à risque : Recherche full-text sur SQLite (limitations si >10k items), stockage fichiers local (backup manuel nécessaire), authentification simpliste <!-- complété par codex -->
+- 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 <!-- complété par codex -->
 
----
-
-## Exemple (a supprimer)
-- Modules : `auth`, `users`, `billing`, `catalog`.
-- DB : PostgreSQL + migrations.
-- Auth : JWT (jeton) + RBAC (contrôle d’accès par rôle).
+---