Budget Tracker Constitution

Core Principles

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.

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.

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/).

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.

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).

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)

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).

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