<!--
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