# LifeTrack — Synthèse du design (v1)

> Tracker de vie auto-hébergé : sport/calories/poids, arrêt de la cigarette (vape), et finances
> personnelles — interface web riche en graphiques, déployée via Docker Compose.

## Documents de référence

| Document | Contenu |
|---|---|
| [docs/design/architecture.md](docs/design/architecture.md) | Architecture technique complète : monorepo, FastAPI, React, auto-découverte des modules, framework de connecteurs, Docker. **§10 = CONVENTIONS (extrait dans [CONVENTIONS.md](CONVENTIONS.md))** |
| [docs/design/datamodel-health-vape.md](docs/design/datamodel-health-vape.md) | Tables + formules santé/nutrition/vape : BMR/TDEE, tendance EMA, projections, coût/ml, économies |
| [docs/design/datamodel-finance.md](docs/design/datamodel-finance.md) | Tables + logique finances : pipeline d'import, dédup, moteur de règles, virements, récurrents, budgets |
| [docs/design/ux-pages.md](docs/design/ux-pages.md) | Spec UX française page par page : ~30 graphiques ECharts, KPI, modales, palette validée daltonisme |
| [docs/research/health-connect.md](docs/research/health-connect.md) | Comment sortir les données de Health Connect (bridge webhook, Health Sync CSV, app compagnon v2) |
| [docs/research/nutrition-sources.md](docs/research/nutrition-sources.md) | Foodvisor (export RGPD), Open Food Facts, CIQUAL, importeurs CSV nutrition |
| [docs/research/finance-sources.md](docs/research/finance-sources.md) | Formats CSV réels de 10 banques FR + PayPal, OFX, Enable Banking (v2) |

## Stack (décidée)

- **Backend** : Python 3.12 (Docker) · FastAPI · SQLAlchemy 2.0 typé · PostgreSQL 16 · PyJWT + argon2
- **Frontend** : React 18 · TypeScript strict · Vite · TailwindCSS (thème sombre) · Apache ECharts · TanStack Query
- **Déploiement** : Docker Compose (postgres + api + web/nginx) ; dev = uvicorn --reload + vite
- **Langues** : code en anglais, UI et messages d'erreur en français (fr-FR : `1 234,56 €`, `dd/MM/yyyy`)

## Décisions structurantes

1. **Modules auto-découverts** des deux côtés (pkgutil côté API, `import.meta.glob` côté web) :
   ajouter un module = créer un dossier, personne ne modifie `main.py`/`router.tsx` → chantiers
   parallèles sans conflit, extensibilité maximale (« l'appli peut aller dans plein de sens »).
2. **Framework de connecteurs** à deux voies : importeurs de **fichiers** (`BaseImporter`,
   `POST /api/imports`, suivi `ImportRun`, dédup idempotente) et handlers d'**ingestion JSON**
   (`BaseIngestHandler`, `POST /api/ingest/{domain}`, clés d'appareil à scopes `ingest:<domain>`).
3. **Dédup normalisée** : `(user_id, source, external_id)` + `(user_id, content_hash)` pour les
   événements ; `(user_id, day, source)` + upsert pour les agrégats journaliers → ré-imports sûrs.
4. **Health Connect = push, jamais pull** (données on-device, pas d'API cloud ; Google Fit API
   morte). v1 : endpoint d'ingestion + app bridge `health-connect-webhook` + import CSV Health
   Sync ; v2 : app compagnon Android (Kotlin, 3-5 j) ; v2/v3 : tapis via Web Bluetooth FTMS.
5. **Nutrition v1** : saisie rapide + recherche Open Food Facts (proxy backend + cache) + table
   CIQUAL + import CSV Foodvisor (export RGPD) ; connecteur Foodvisor natif impossible (pas d'API).
6. **Finances v1 = fichiers** : mapper CSV générique + presets par banque (10 banques FR),
   OFX, PayPal ; aperçu avant import + rollback par lot. **v2 = Enable Banking** (PSD2 gratuit
   pour ses propres comptes — GoCardless/Nordigen ferme, ne pas construire dessus).
7. **Vape** : modèle de coût DIY historisé (base, boosters, arômes, résistances) → coût/ml,
   coût/jour avec amortissement résistance, économies cumulées vs baseline cigarettes gelée.
8. **Temps** : stockage UTC `timestamptz`, jours locaux `Date` en Europe/Paris (`?tz=` sur les
   agrégations). **Unités canoniques** : kg, cm/m, ml, kcal, secondes, centimes d'euro.
9. **v1 sans Alembic** : `metadata.create_all` au démarrage (migrations ajoutées quand le schéma
   bougera). Tests pytest sur SQLite → types portables (voir CONVENTIONS C8).
10. **Graphiques** : palette 8 couleurs validée daltonisme sur fond sombre, jamais de double axe Y,
    sémantique directionnelle (déficit/économies = vert), réponses stats déjà au format ECharts.

## Périmètre v1 (ce dépôt) / v2 / v3

- **v1** : tout le web + API ci-dessus, imports fichiers, ingestion JSON Health Connect (bridge),
  dashboards complets, wizard premier démarrage.
- **v2** : app compagnon Android Health Connect, connecteur Enable Banking, calculateur DIY avancé,
  Alembic, notifications.
- **v3** : enregistrement tapis Web Bluetooth FTMS, analyse photo repas (si API Foodvisor s'ouvre),
  multi-utilisateurs complet, thème clair.