12 KiB
12 KiB
🏋️ HabitForge
Plateforme auto-hébergée de suivi d'habitudes, de santé et de fitness avec companion app Android
📖 Vue d'Ensemble
HabitForge est bien plus qu'un simple tracker d'habitudes. C'est une plateforme complète qui combine :
- 🎯 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.