budget-tracker/.specify/memory/research.md

Recherche & Décisions Techniques — Budget Tracker

Authentification

• Décision : JWT (tokens access 15min + refresh 7j) via python-jose + passlib[bcrypt]
• Rationale : stateless, compatible SPA React, aucune session serveur à gérer, facile à dockeriser
• Alternatives :
  • Session cookies (plus simple mais couplé au serveur, complexe en CORS)
  • OAuth2 externe / Keycloak (overkill pour usage personnel)
  • FastAPI-Users (bibliothèque haut niveau — ajoute de la magie, préférence pour la transparence)

Base de données

• Décision : PostgreSQL 16
• Rationale : ACID natif (critique pour données financières), types UUID, ENUM, support transactionnel, standard de l'industrie
• Alternatives :
  • SQLite (suffisant en dev, mais limité en concurrence et types)
  • MySQL (moins bon support UUID/ENUM natif)

ORM & Migrations

• Décision : SQLAlchemy 2.0 (mode async) + Alembic
• Rationale : async natif pour FastAPI, migrations versionées et réversibles, mature et bien documenté
• Alternatives :
  • Tortoise ORM (async natif mais moins mature, moins d'intégrations)
  • SQLModel (wrapper SQLAlchemy+Pydantic — moins de contrôle sur les modèles)
  • Prisma (Node.js uniquement)

Framework Backend

• Décision : FastAPI 0.111+
• Rationale : OpenAPI/Swagger auto-généré (conforme principe I de la Constitution), validation Pydantic intégrée, async natif, typage strict
• Alternatives :
  • Django REST Framework (sync-first, plus lourd)
  • Flask (pas d'async natif, validation manuelle)

Framework Frontend

• Décision : React 18 + TypeScript + Vite
• Rationale : écosystème riche, SPA adaptée à une app de gestion, typage fort réduit les erreurs sur les montants financiers
• Alternatives :
  • Next.js (SSR inutile pour usage authentifié perso)
  • Vue 3 (viable mais écosystème plus réduit)

Styling Frontend

• Décision : Tailwind CSS 3 + shadcn/ui
• Rationale : utilitaires CSS rapides, shadcn/ui fournit composants accessibles (formulaires, modales, tableaux) sans dépendance lourde
• Alternatives :
  • MUI / Ant Design (plus lourds, style moins personnalisable)
  • CSS Modules (trop verbeux pour une SPA)

Graphiques Frontend

• Décision : Recharts
• Rationale : composants React purs (pas de D3 direct), bon support responsive, Tailwind-compatible, léger (~180 ko gzip)
• Alternatives :
  • Chart.js + react-chartjs-2 (moins idiomatic React, state management externe)
  • Nivo (très complet mais plus lourd, over-engineering pour 2 types de graphiques)
  • Victory (moins maintenu)

Gestion d'état Frontend

• Décision : TanStack Query (React Query) v5
• Rationale : cache serveur, invalidation automatique après mutations (soldes recalculés), gestion loading/error intégrée — évite un store global Redux pour des données essentiellement serveur
• Alternatives :
  • Redux Toolkit (overkill, état global inutile si les données viennent de l'API)
  • SWR (moins de fonctionnalités sur les mutations)
  • Zustand (utile pour état local UI uniquement, complémentaire)

Export CSV

• Décision : module csv Python stdlib
• Rationale : aucune dépendance additionnelle, suffisant pour colonnes tabulaires de transactions, streaming possible via StreamingResponse FastAPI
• Alternatives :
  • pandas (overkill, dépendance lourde)

Export PDF

• Décision : WeasyPrint
• Rationale : rendu HTML→PDF côté serveur, templates Jinja2 réutilisables, CSS support correct, rendu fidèle
• Alternatives :
  • ReportLab (API bas niveau, verbeux pour des tableaux)
  • pdfkit (dépendance système wkhtmltopdf, difficile à dockeriser)
  • Reportlab + xhtml2pdf (moins stable)

Stockage des montants

• Décision : entiers en centimes (amount_cents INTEGER)
• Rationale : conforme au principe II de la Constitution — élimine toute erreur d'arrondi IEEE 754 sur les opérations financières (ex : 0.1 + 0.2 ≠ 0.3 en float)
• Règle : la conversion euros↔centimes se fait uniquement aux frontières (serialisation Pydantic et affichage React)

Soft Delete

• Décision : champ deleted_at TIMESTAMP NULL sur Transaction et Category
• Rationale : conforme au principe II (tracabilité historique), permet l'audit et la restauration éventuelle
• Implémentation : filtre WHERE deleted_at IS NULL systématique dans les requêtes ; index partiel recommandé

Conteneurisation

• Décision : Docker Compose (backend + frontend + PostgreSQL)
• Rationale : conforme au principe V de la Constitution, reproductibilité dev/prod, un seul docker compose up
• Structure :
  • backend/ — image Python 3.12-slim
  • frontend/ — build Vite servi par Nginx
  • db/ — PostgreSQL 16 officiel

Tests Backend

• Décision : pytest + httpx (client async) + pytest-asyncio + base de données de test dédiée
• Rationale : conforme au principe III (80% coverage services/), tests d'intégration sur vraie BDD (pas de mock SQLAlchemy)
• Alternatives :
  • unittest (moins expressif)
  • mocks SQLAlchemy (rejeté — risque de divergence mock/prod)