home_stock/backend/CONTEXT.md

Contexte backend

Ce document décrit le rôle du backend, ses responsabilités et ses choix techniques. Tout ce qui est indiqué ici est la référence pour les agents backend.

---

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é backend.

---

Objectif du backend

• Problème métier couvert : Centraliser et structurer les données d'inventaire domestique avec recherche efficace et gestion de fichiers
• Responsabilités principales : API REST CRUD (items, locations, categories), upload/stockage fichiers, recherche full-text, validation données, génération OpenAPI
• Hors périmètre : Rendu frontend (SPA indépendante), authentification complexe (MVP mono-utilisateur), analytics avancées

Interfaces

• API publique : REST JSON à /api/v1/, OpenAPI 3.0 auto-générée à /docs, endpoints principaux = items, locations, categories, documents, search
• Authentification/autorisation : Optionnelle pour MVP (déploiement local), si activée = session cookie basique, pas de rôles complexes (mono-utilisateur)
• Intégrations externes : Aucune intégration externe, système autonome

Données

• Base(s) utilisée(s) : SQLite (fichier homestock.db) avec extension FTS5 pour recherche full-text
• Modèle de données clé : Item (objet principal), Location (hiérarchie lieu/meuble/tiroir), Category (domaine), Document (fichier), relations Many-to-One et Many-to-Many
• Stratégie de migration : Alembic pour migrations versionnées, auto-génération à partir des modèles SQLAlchemy, migrations réversibles up/down

Architecture interne

• Style : Monolithe modulaire avec séparation claire routers → services → repositories (3-layer architecture)
• Modules principaux : routers/ (endpoints FastAPI), services/ (logique métier), models/ (ORM SQLAlchemy), schemas/ (Pydantic validation), repositories/ (accès BDD)
• Couche d'accès aux données : Repository pattern avec SQLAlchemy async sessions, abstraction BDD pour faciliter tests et évolution

Qualité & exploitation

• Observabilité : Logs structurés avec loguru (format JSON), endpoint /health pour healthcheck, pas de tracing distribué (monolithe)
• Tests : pytest avec tests unitaires (services/), tests intégration (routers/ avec TestClient), fixtures pour BDD test, couverture 70%+ sur logique métier
• Performance attendue : Réponse API <200ms pour GET simple, <500ms pour recherche full-text, upload fichiers <5s pour 10MB, pas de contrainte scalabilité (mono-utilisateur)

Conventions

• Organisation du code : backend/app/ racine, sous-dossiers par responsabilité (routers/, services/, models/, schemas/, repositories/), un fichier par entité
• Nommage : snake_case pour tout (variables, fonctions, fichiers), préfixes get_/create_/update_/delete_ pour CRUD, suffixes _service/_repository selon couche
• Gestion erreurs : HTTPException FastAPI pour erreurs API avec codes standards (400/404/500), exceptions métier custom héritant de BaseException, logging erreurs avec contexte

---