🎯 Suivi d'habitudes avec défis personnalisables (reps, minutes, km, pages...)
📊 Dashboard santé connecté à Health Connect (Android) et Zepp/Amazfit
📱 Companion app Android pour synchronisation automatique des données de santé
🧠 Analytics avancés : readiness score, corrélations, tendances
🏗️ Architecture scalable : SQLite pour le dev, PostgreSQL pour la prod

✨ Fonctionnalités

🎯 Challenges & Habitudes

Défis flexibles : quotidien, hebdomadaire (jours spécifiques), mensuel, annuel
Multi-unités : reps, minutes, pages, kilomètres
Jours de repos configurables
15 exercices animés (GIFs) comme références visuelles
Icônes FontAwesome personnalisables
Drag & drop pour réorganiser les priorités
Statistiques : streak, taux de complétion, reps totales
Heatmap de consistance (vue calendrier)

📊 Dashboard Santé

Widgets interactifs avec jauges semi-circulaires (Canvas API)
- Steps quotidiens
- Calories brûlées
- Fréquence cardiaque (min/max/repos)
- SpO2
- Poids (lbs/kg) & BMI avec tendances
Décomposition du sommeil : profond, léger, REM, éveillé
Graphiques d'historique (Chart.js) : 7j, 30j, 365j
Readiness Score quotidien basé sur HRV, RHR et sommeil
Contexte subjectif : humeur, tags, notes

📱 Android Companion App

Lecture native Health Connect (tous les types de données)
Sync automatique configurable (1h, 3h, 6h, 12h, 24h)
15 types de données brutes synchronisées (steps, HR, sleep stages, SpO2, poids, nutrition...)
Historique des synchronisations avec stats détaillées
Test de connexion serveur avec temps de réponse
Validation de schéma des données avant sync
Indicateur de statut serveur en temps réel

🔄 Intégrations

Health Connect (Android) — sync native via companion app
Zepp/Amazfit — import CSV des données exportées
Architecture Provider — extensible pour futures sources (Google Fit, Apple Health, Garmin...)
Agrégation on-demand — calcul des métriques à partir des données brutes

🎨 UX/UI

Mobile-First design (Tailwind CSS)
Dark Mode avec persistance
Jauges animées Canvas pour poids et BMI
Modales pour détails des métriques
Navigation par onglets fluide

🛠 Stack Technique

Backend

Composant	Technologie
Framework	FastAPI 0.141
ORM	SQLAlchemy 2.0
Auth	JWT (OAuth2 Password Flow) + Argon2
Validation	Pydantic 2.0
Rate Limiting	SlowAPI
Migrations	Alembic
Server	Uvicorn (dev) / Gunicorn + Uvicorn Workers (prod)

Frontend

Composant	Technologie
Core	Vanilla JavaScript (ES6+)
CSS	Tailwind CSS (CDN)
Charts	Chart.js
Icons	FontAwesome 6
Animations	Anime.js + Canvas API
Drag & Drop	SortableJS

Android

Composant	Technologie
Langage	Kotlin
HTTP Client	Retrofit
Health SDK	Android Health Connect API
UI	Jetpack + Material Design
Auth	JWT token management

Infrastructure

Environnement	Configuration
Dev simple	`docker-compose.yml` — SQLite
Dev complet	`docker-compose.dev.yml` — PostgreSQL + CloudBeaver
Production	`docker-compose.prod.yml` — Nginx + Gunicorn + Backup auto

🚀 Démarrage Rapide

Prérequis

Docker & Docker Compose
Git LFS (pour les GIFs)

Dev complet (PostgreSQL + interface DB)

git clone https://git.dracodev.net/Projets/HabitForge.git
cd HabitForge
docker compose -f docker-compose.dev.yml up -d --build

Accès :

🌐 App : http://localhost:8000
🗄️ CloudBeaver (DB GUI) : http://localhost:8978 (admin/admin)
📖 API Docs : http://localhost:8000/docs

Mode simple (SQLite)

docker compose up -d --build

Production (Nginx + backup auto)

# Configurer .env.production d'abord
docker compose -f docker-compose.prod.yml up -d --build

📂 Structure du Projet

HabitForge/
├── backend/                     # API FastAPI
│   ├── api/v1/                  # Routes REST
│   │   ├── auth.py              #   Authentification JWT
│   │   ├── challenges.py        #   CRUD Challenges + Tracking
│   │   ├── health.py            #   Stats santé + Workouts
│   │   ├── health_connect.py    #   Sync Health Connect (legacy)
│   │   ├── health_connect_raw.py#   Sync données brutes (15 types)
│   │   └── health_analytics.py  #   Analytics + Readiness Score
│   ├── core/config.py           # Configuration (pydantic-settings)
│   ├── models/                  # 25 modèles SQLAlchemy
│   │   ├── user.py              #   Comptes utilisateurs
│   │   ├── challenge.py         #   Défis
│   │   ├── tracking.py          #   Suivi quotidien
│   │   ├── daily_health_metrics.py  # Métriques agrégées legacy
│   │   ├── daily_context.py     #   Contexte subjectif (mood)
│   │   ├── workout_session.py   #   Sessions manuelles
│   │   ├── health_connect.py    #   Sync logs + métriques HC
│   │   └── health_connect_raw.py#   15 tables raw HC
│   ├── services/                # Couche métier
│   │   ├── auth_service.py
│   │   ├── challenge_service.py
│   │   ├── health_service.py
│   │   └── aggregation_service.py  # Agrégation on-demand
│   ├── integrations/            # Providers données santé
│   │   ├── health_provider.py   #   Interface abstraite
│   │   ├── health_connect_provider.py
│   │   └── import_zepp.py       #   Import CSV Zepp
│   ├── schemas/                 # Validation Pydantic
│   ├── repositories/            # Data access layer
│   └── database.py              # Engine + Session
├── frontend/                    # SPA vanilla JS
│   ├── index.html               # Dashboard principal
│   ├── login.html               # Page login
│   ├── app.js                   # Logique applicative (4300+ lignes)
│   └── static/                  # 15 GIFs d'exercices (LFS)
├── android-companion/           # App Android Kotlin
│   └── app/src/main/java/com/habitforge/companion/
│       ├── MainActivity.kt      # UI principale
│       ├── HealthConnectManager.kt  # Lecture Health Connect
│       ├── SyncService.kt       # Service background
│       ├── RawDataSyncService.kt# Sync données brutes
│       ├── HabitForgeApi.kt     # Client Retrofit
│       └── ...                  # 17 fichiers Kotlin au total
├── alembic/                     # Migrations DB (9 versions)
├── nginx/                       # Config Nginx + SSL
├── scripts/                     # Utilitaires
│   ├── import_zepp_data.py      # Import données Zepp
│   ├── migrate_to_postgres.py   # Migration SQLite → PostgreSQL
│   └── backup_db.sh             # Backup automatique PostgreSQL
├── docker-compose.yml           # Dev simple (SQLite)
├── docker-compose.dev.yml       # Dev complet (PostgreSQL + CloudBeaver)
├── docker-compose.prod.yml      # Production (Nginx + Gunicorn + Backup)
├── Dockerfile                   # Image Python 3.10-slim
├── requirements.txt             # Dépendances Python
├── DATABASE_SCHEMA.md           # Schémas Mermaid
└── ROADMAP.md                   # Roadmap & état du projet

🔌 API — Principaux Endpoints

Méthode	Endpoint	Description
`POST`	`/api/auth/register`	Créer un compte
`POST`	`/api/auth/token`	Obtenir un JWT
`POST`	`/api/auth/refresh`	Rafraîchir le JWT
`GET`	`/api/auth/me`	Profil utilisateur
`GET/POST/PUT/DELETE`	`/api/challenges[/{id}]`	CRUD Challenges
`POST`	`/api/tracking`	Logger une répétition
`GET`	`/api/health`	Health check DB
`GET`	`/api/health/stats`	Statistiques santé (période)
`GET`	`/api/health/workouts`	Sessions d'entraînement
`POST`	`/api/health-connect/sync-raw`	Sync données brutes (15 types)
`GET`	`/api/analytics/daily`	Analytics quotidien (avec readiness)
`GET`	`/api/analytics/range`	Analytics plage de dates
`POST`	`/api/analytics/context`	Mise à jour mood/tags

📖 Documentation interactive : http://localhost:8000/docs (Swagger) | http://localhost:8000/redoc

📊 Schéma de Base de Données

Le projet contient 25 tables organisées en 3 couches :

Couche	Tables	Description
Core	6	users, challenges, tracking, daily_health_metrics, daily_context, workout_sessions
Health Connect Aggregated	3	sync_logs, daily_metrics, exercise_sessions
Health Connect Raw	15	steps, heart_rate + samples, resting_hr, sleep_sessions + stages, distance, calories, spo2, weight, height, body_fat, exercise_sessions, nutrition, hydration, hrv_rmssd

➡️ Voir DATABASE_SCHEMA.md pour les diagrammes Mermaid complets.

🗺️ Roadmap

➡️ Voir ROADMAP.md pour l'état détaillé des fonctionnalités et la vision future.

Priorités actuelles

🔴 Tests automatisés (pytest)
🔴 Cache d'agrégation (performances)
🟡 Badges & Achievements
🟡 Export de données

🔧 Configuration

Copier le fichier d'exemple et adapter :

cp .env.example .env.development

Variables principales

Variable	Description	Défaut
`SECRET_KEY`	Clé de chiffrement JWT	À définir
`DATABASE_URL`	Chaîne de connexion DB	`sqlite:///./data/habitforge.db`
`CORS_ORIGINS`	Origines autorisées	`http://localhost:8000`
`GOOGLE_CLIENT_ID`	OAuth Google	`""`
`HEALTH_PROVIDER`	Provider santé	`"health_connect"`
`RATE_LIMIT_ENABLED`	Rate limiting	`true`
`DEBUG`	Mode debug	`true`

📱 Companion App Android

L'application Android se synchronise avec votre instance HabitForge pour importer automatiquement vos données Health Connect.

Build

cd android-companion
./gradlew assembleDebug
# APK dans app/build/outputs/apk/debug/

Données synchronisées

Steps • Distance • Calories • Fréquence cardiaque • FC repos • Sommeil (phases) • SpO2 • Poids • Taille • Masse grasse • Sessions d'exercice • Nutrition • Hydratation • HRV

➡️ Voir android-companion/README.md pour la documentation complète.

📥 Import Zepp/Amazfit

Si vous utilisez une montre Zepp/Amazfit, vous pouvez importer vos données :

# Placer l'export dans export-zepp/
docker compose -f docker-compose.dev.yml exec web python scripts/import_zepp_data.py

➡️ Voir ZEPP_IMPORT.md pour les détails.

🤝 Contribuer

Fork le projet
Branche feature : git checkout -b feature/AmazingFeature
Commit : git commit -m 'Add AmazingFeature'
Push : git push origin feature/AmazingFeature
Pull Request

Le projet utilise ruff pour le linting Python et pre-commit pour les hooks.

📄 Licence

MIT License — voir le fichier LICENSE.