home_hub/README.md

HomeHub

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

Fonctionnalités

• Todos — tâches classées par domaine (informatique, DIY, jardinage, cuisine…)
• Liste de courses — générée depuis les habitudes d'achat, mode magasin avec Wake Lock, suivi des prix, OCR étiquettes et tickets
• Notes — saisie rapide avec photo, audio, GPS et métadonnées libres
• MCP Server — expose les données à des agents IA (Hermes, Claude, etc.)

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 (développement local)

# Copier la configuration
cp .env.example .env

# Lancer l'environnement de développement
./dev.sh

# Backend disponible sur http://localhost:8000
# Frontend disponible sur http://localhost:3000
# Documentation API : http://localhost:8000/docs

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)

Évolutions prévues

• Authentification multi-utilisateurs (JWT)
• Sync Google Calendar + CalDAV iOS
• Intégration Home Assistant
• Webhooks Gitea → Kanban
• Analyse frigo par Vision LLM (Hermes/Ollama)