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

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 :

# 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 :

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 — features détaillées, schéma DB, interfaces
• Plan de développement — phases et tâches
• Design system — composants et règles visuelles
• API REST : http://localhost:8000/docs (Swagger auto-généré par FastAPI)

Déploiement (Proxmox)

# 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)

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

# 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)