# HomeHub

Application d'organisation personnelle auto-hébergée — PWA mobile-first déployée sur Proxmox 9.

## Fonctionnalités (v0.5.1)

- **Todos** — tâches classées par domaine, priorité, date objectif, photo, GPS. Swipe gauche = éditer, swipe droite = terminer.
- **Liste de courses** — générée automatiquement depuis les habitudes d'achat (liste magique), mode magasin plein-écran avec Wake Lock, catalogue enrichi avec tags et stats d'achat, bottom sheet multi-select.
- **Notes** — saisie rapide avec photo (Ctrl+V ou appareil photo), audio, GPS et métadonnées libres.
- **Paramètres** — thème dark / light / system, taille de police ajustable avec aperçu temps réel.
- **MCP Server** — expose les données à des agents IA (Hermes, Claude, etc.) — *à venir*

### UX mobile
- Touch targets 48px minimum, swipe gestures sur toutes les listes
- Bottom sheet qui remonte automatiquement au-dessus du clavier virtuel iOS
- Collage d'image par Ctrl+V dans les formulaires Todo et Catalogue
- Wake Lock API (écran allumé en mode magasin)

## Stack technique

| Composant | Technologie |
|-----------|-------------|
| Frontend | React 18 + Vite + TypeScript + Tailwind CSS |
| Backend | Python 3.12 + FastAPI (async) |
| Base de données | PostgreSQL 16 (schémas multiples) |
| Migrations | Alembic |
| OCR | Tesseract 5 (service Docker dédié, partagé entre modules) |
| Scan code-barres | zxing-js (frontend, iOS + Android) |
| Catalogue produits | OpenFoodFacts API (~3M produits alimentaires) |
| Recherche image | SearXNG (auto-hébergé, fallback image produits) |
| Déploiement | Docker Compose · Nginx Proxy Manager |
| Design system | Gruvbox seventies (`design_system/`) |

## Démarrage rapide

```bash
cd ~/Documents/projet/home_hub

# Lancer l'app (première fois ou après un arrêt)
docker compose up -d

# Frontend  → http://localhost:3001  (ou http://<IP-locale>:3001 sur le réseau)
# API Swagger → http://localhost:8000/docs
```

**Après modification du code :**
```bash
# Rebuild + relancer un service
docker compose build backend && docker compose up -d backend
docker compose build frontend && docker compose up -d frontend

# Rebuild tout
docker compose build && docker compose up -d
```

**Maintenance :**
```bash
docker compose down          # Arrêter (données conservées)
docker compose logs -f       # Logs en direct
docker compose ps            # État des conteneurs
```

## Structure du projet

```
home_hub/
├── ocr/
│   ├── app.py            # Service FastAPI OCR (Tesseract + Pillow)
│   └── Dockerfile
├── product-search/
│   ├── app.py            # Client OpenFoodFacts + proxy SearXNG images
│   └── Dockerfile
├── backend/
│   ├── app/
│   │   ├── api/          # Endpoints par domaine (todos, shopping, notes, media, mcp)
│   │   ├── core/         # Config, base de données, middleware
│   │   ├── models/       # Modèles SQLAlchemy
│   │   ├── schemas/      # Schémas Pydantic
│   │   └── services/
│   │       ├── media.py  # Upload, compression, génération miniatures (Pillow)
│   │       ├── ocr.py    # Client vers service ocr:8001
│   │       └── ...       # Suggestions shopping, sync calendrier (futur)
│   ├── alembic/          # Migrations de base de données
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/   # Composants React
│   │   ├── pages/        # Pages par module
│   │   ├── hooks/        # Hooks personnalisés (camera, geolocation, wake-lock…)
│   │   └── api/          # Client API typé
│   ├── public/
│   │   └── manifest.json
│   ├── Dockerfile
│   └── vite.config.ts
├── design_system/        # Design system Gruvbox seventies (tokens + composants)
├── docs/
│   ├── spec.md           # Spécification fonctionnelle complète
│   └── plan.md           # Plan de développement par phases
├── docker-compose.yml
├── docker-compose.dev.yml
└── .env.example
```

## Documentation

- [Spécification fonctionnelle](docs/spec.md) — features détaillées, schéma DB, interfaces
- [Plan de développement](docs/plan.md) — phases et tâches
- [Design system](design_system/README.md) — composants et règles visuelles
- API REST : `http://localhost:8000/docs` (Swagger auto-généré par FastAPI)

## Déploiement (Proxmox)

```bash
# Production
docker compose up -d

# Nginx Proxy Manager pointe vers :
#   homehub.local → frontend:3000
#   homehub.local/api → backend:8000
#   homehub.local/mcp → backend:8000/mcp (pour les agents IA)
```

## Déploiement via registre OCI Gitea

Les images finales sont publiées sur le registre OCI privé `git.maison43gil.com`
(source unique de vérité). Deux images sous le paquet `home_hub`, distinguées par tag :

| Image | Tag |
|-------|-----|
| Backend (FastAPI) | `git.maison43gil.com/gilles/home_hub:backend-latest` |
| Frontend (Nginx) | `git.maison43gil.com/gilles/home_hub:frontend-latest` |

### Construction & publication (manuel)

```bash
docker login git.maison43gil.com

# Backend
docker build -t git.maison43gil.com/gilles/home_hub:backend-latest ./backend
docker push git.maison43gil.com/gilles/home_hub:backend-latest

# Frontend
docker build -t git.maison43gil.com/gilles/home_hub:frontend-latest ./frontend
docker push git.maison43gil.com/gilles/home_hub:frontend-latest
```

> Le registre est derrière Nginx Proxy Manager : pour les gros blobs (image
> backend ~1.3 Go), régler `client_max_body_size 0;` dans l'onglet Advanced
> du proxy host `git.maison43gil.com` (sinon erreur `413 Payload Too Large`).

### Construction automatique (Gitea Actions)

`.gitea/workflows/build.yml` build et push les deux images :
- push sur `main` → tags `*-latest`
- tag git `vX.Y.Z` → tags `*-latest` + `*-X.Y.Z`

### Déploiement sur le serveur

```bash
# Sur le serveur de production
git pull                         # récupère docker-compose.deploy.yml + .env.example
cp .env.example .env             # compléter les secrets (POSTGRES_PASSWORD, MCP_API_KEY…)

docker login git.maison43gil.com
docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -d
```

Le service `backend-migrate` applique automatiquement les migrations Alembic
(`alembic upgrade head`) avant le démarrage du backend. Aucune image n'est
reconstruite en production (pas de `build:`).

### Environnements

| Fichier | Usage | Images |
|---------|-------|--------|
| `docker-compose.yml` | Dev (build local) | `build:` |
| `docker-compose.dev.yml` | Override dev (HMR + `--reload`) | `build:` |
| `docker-compose.deploy.yml` | **Production** | `image:` (OCI Gitea) |

## Évolutions prévues

- **Phase 5** — Scan code-barres (zxing-js) + enrichissement catalogue via OpenFoodFacts
- **Phase 6** — Service OCR dédié (Tesseract 5, conteneur partagé)
- **Phase 7** — Shopping avancé : OCR étiquettes prix, historique et comparaison prix par magasin
- **Phase 8** — MCP Server : outils IA (`get_todos`, `add_shopping_item`, `search_notes`…)
- **Phase 9** — Authentification multi-utilisateurs (JWT)
- **Phase 10** — Calendrier : sync Google Calendar + CalDAV iOS, intégration Home Assistant, webhooks Gitea
- **Phase 11** — Vision LLM : analyse frigo → suggestions liste de courses (Hermes/Ollama)