feat: budget-tracker — spec, constitution, data-model, API contracts, plan

.specify/memory/constitution.md

@@ -0,0 +1,120 @@
+<!--
+Sync Impact Report
+- Version change: N/A → 1.0.0 (initial ratification)
+- Added principles: I. API-First, II. Data Integrity, III. Test Coverage,
+  IV. Simplicity & Pragmatism, V. Docker-First Deployment
+- Added sections: Technical Stack Constraints, Development Workflow, Governance
+- Removed sections: none
+- Templates requiring updates:
+  - .specify/templates/plan-template.md ✅ compatible (Constitution Check present)
+  - .specify/templates/spec-template.md ✅ compatible (priorities, acceptance scenarios)
+  - .specify/templates/tasks-template.md ✅ compatible (phased approach, test-optional)
+- Follow-up TODOs: none
+-->
+
+# Budget Tracker Constitution
+
+## Core Principles
+
+### I. API-First Design
+
+Le backend FastAPI expose une API REST documentee (OpenAPI/Swagger) qui
+constitue le contrat unique entre frontend et backend.
+
+- Chaque endpoint DOIT etre defini dans un schema OpenAPI avant implementation.
+- Le frontend React consomme exclusivement l'API REST ; aucun acces direct
+  a la base de donnees depuis le frontend.
+- Les reponses DOIVENT suivre un format JSON coherent avec codes HTTP
+  standards (200, 201, 400, 404, 422, 500).
+- La validation des entrees DOIT utiliser les modeles Pydantic de FastAPI.
+
+### II. Data Integrity
+
+Les donnees financieres sont critiques et DOIVENT etre exactes et coherentes.
+
+- Tous les montants DOIVENT etre stockes en centimes (entiers) pour eviter
+  les erreurs d'arrondi en virgule flottante.
+- Les operations affectant le solde DOIVENT etre transactionnelles (ACID).
+- Chaque transaction DOIT avoir une date, un montant, une categorie et un type
+  (revenu ou depense).
+- Les suppressions DOIVENT etre des soft-deletes (champ deleted_at) pour
+  garantir la tracabilite de l'historique.
+
+### III. Test Coverage
+
+Les tests couvrent la logique metier critique sans imposer un TDD strict.
+
+- Les calculs financiers (soldes, totaux, budgets) DOIVENT avoir des tests
+  unitaires.
+- Les endpoints API DOIVENT avoir des tests d'integration avec une base de
+  donnees de test.
+- Les tests DOIVENT etre executables via `pytest` en une seule commande.
+- Le coverage minimum cible est 80% sur la logique metier (services/).
+
+### IV. Simplicity & Pragmatism
+
+Pas de sur-ingenierie. Chaque couche d'abstraction DOIT etre justifiee.
+
+- YAGNI : ne pas implementer de fonctionnalite "au cas ou".
+- Pas de pattern Repository si l'acces direct SQLAlchemy suffit.
+- Pas de microservices : monolithe backend + SPA frontend.
+- Les librairies tierces sont preferees a du code custom quand elles
+  resolvent exactement le probleme (ex: Chart.js pour les graphiques).
+- Le code DOIT etre lisible par un developpeur junior sans documentation
+  supplementaire.
+
+### V. Docker-First Deployment
+
+L'application DOIT etre deployable via `docker compose up` sans
+configuration manuelle.
+
+- Un fichier `docker-compose.yml` a la racine DOIT orchestrer backend,
+  frontend et PostgreSQL.
+- Les variables d'environnement DOIVENT etre centralisees dans un `.env`
+  (avec `.env.example` versionne).
+- Les migrations de base de donnees DOIVENT s'executer automatiquement
+  au demarrage du conteneur backend.
+- Le frontend DOIT etre servi en mode production via un build statique
+  (nginx ou equivalent).
+
+## Technical Stack Constraints
+
+- **Backend** : Python 3.12+, FastAPI, SQLAlchemy 2.0 (async), Alembic
+- **Frontend** : React 18+, Tailwind CSS, Vite, Chart.js (ou Recharts)
+- **Base de donnees** : PostgreSQL 16+
+- **Tests** : pytest (backend), Vitest (frontend)
+- **Conteneurisation** : Docker, Docker Compose v2
+- **Langue du code** : anglais (variables, fonctions, fichiers)
+- **Langue de la documentation** : francais
+- Les dependances DOIVENT etre epinglees (versions exactes dans
+  requirements.txt / package.json)
+
+## Development Workflow
+
+- Le code DOIT etre formate automatiquement (Ruff pour Python, Prettier
+  pour JS/TS).
+- Chaque commit DOIT passer le linting et les tests avant merge.
+- Les branches suivent le pattern : `feature/xxx`, `fix/xxx`, `chore/xxx`.
+- Les migrations Alembic DOIVENT etre auto-generees puis relues
+  manuellement avant commit.
+- Le fichier `docker-compose.yml` DOIT inclure un service de
+  developpement avec hot-reload (backend + frontend).
+
+## Governance
+
+Cette constitution est le document de reference pour toutes les decisions
+techniques et architecturales du projet Budget Tracker.
+
+- Tout changement architectural DOIT etre valide contre les principes
+  ci-dessus avant implementation.
+- Les amendements a cette constitution requierent : (1) une justification
+  ecrite, (2) une mise a jour du numero de version, (3) une propagation
+  aux artefacts dependants.
+- Le versionnement suit le Semantic Versioning : MAJOR pour les
+  changements incompatibles, MINOR pour les ajouts, PATCH pour les
+  clarifications.
+- En cas de conflit entre pragmatisme et rigueur, le principe IV
+  (Simplicity & Pragmatism) prevaut sauf pour les donnees financieres
+  (principe II).
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-15 | **Last Amended**: 2026-03-15