# 🏋️ HabitForge

> Plateforme auto-hébergée de suivi d'habitudes, de santé et de fitness avec companion app Android

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.141-009688.svg)
![Kotlin](https://img.shields.io/badge/Kotlin-Android-purple.svg)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15-336791.svg)

---

## 📖 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)
```bash
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)
```bash
docker compose up -d --build
```

### Production (Nginx + backup auto)
```bash
# 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`](./DATABASE_SCHEMA.md) pour les diagrammes Mermaid complets.

---

## 🗺️ Roadmap

➡️ Voir [`ROADMAP.md`](./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 :

```bash
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
```bash
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`](./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 :

```bash
# 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`](./ZEPP_IMPORT.md) pour les détails.

---

## 🤝 Contribuer

1. Fork le projet
2. Branche feature : `git checkout -b feature/AmazingFeature`
3. Commit : `git commit -m 'Add AmazingFeature'`
4. Push : `git push origin feature/AmazingFeature`
5. Pull Request

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

---

## 📄 Licence

MIT License — voir le fichier `LICENSE`.