home_hub/docs/spec.md

HomeHub — Spécification Fonctionnelle

Version 0.1 — mai 2026
Application d'organisation personnelle auto-hébergée (PWA)
Stack : FastAPI · React/Vite/TypeScript · PostgreSQL 16 · Docker Compose

---

1. Contexte et objectifs

HomeHub est une PWA auto-hébergée sur Proxmox 9, conçue pour un usage intensif mobile (smartphone en magasin, sur le terrain) et une consultation plus complète sur laptop. L'application est mono-utilisateur au démarrage, avec une architecture prévue pour évoluer vers le multi-utilisateur sans refactoring majeur (colonne owner_id nullable dans toutes les tables).

---

2. Architecture technique

2.1 Services Docker Compose (6 services)

Service	Image	Port interne	Rôle
frontend	Nginx léger	3000	Sert le build React/Vite (PWA statique)
backend	Python 3.12 / FastAPI	8000	API REST + MCP server
db	PostgreSQL 16	5432	Base de données multi-schémas
ocr	Tesseract + Pillow	8001	Service OCR partagé (toutes les photos de l'app)
product-search	Python slim	8002	Lookup OpenFoodFacts + fallback SearXNG
searxng	SearXNG officiel	8080	Métamoteur de recherche — fallback image produits

Services isolés et arrêtables indépendamment :

• ocr (4) — arrêtable sans impact sur la liste de courses. Seule la saisie OCR de prix devient indisponible
• product-search (5) — arrêtable sans impact. Seule la recherche OpenFoodFacts devient indisponible
• searxng (6) — arrêtable sans impact. Seul le fallback image produit devient indisponible

Les services 1/2/3 (frontend, backend, db) sont les seuls obligatoires pour le fonctionnement de base. Un docker compose stop ocr product-search searxng laisse l'app 100% fonctionnelle pour la liste de courses.

Nginx Proxy Manager (déjà en place sur le homelab) gère l'entrée HTTPS et le routage vers ces services.

2.2 Évolutions prévues (non bloquantes)

• Redis → ajouté avec la sync Google Calendar (Phase 6)
• Auth JWT → activation de owner_id + écran de connexion (Phase 7)
• Agent Hermes (Vision LLM) → analyse photo frigo
• Webhooks Gitea → intégration Kanban
• Home Assistant → capteurs tâches en retard

2.3 Stockage fichiers et module media

Volume Docker /uploads/ servi par le backend. Toutes les images passent par le module media du backend à la réception.

Pipeline de traitement à l'upload :

1. Compression côté client (Canvas API → WebP) avant envoi — réduit la bande passante
2. Validation format serveur (JPG, PNG, SVG, WebP acceptés)
3. Génération automatique d'une miniature (Pillow) — stockée séparément
4. Les deux fichiers sont enregistrés sur le volume

Structure du volume :

/uploads/
  images/
    originals/{uuid}.webp       ← image compressée (pleine résolution utile)
    thumbnails/{uuid}_thumb.webp ← miniature générée par Pillow
  audio/
    {uuid}.webm                 ← enregistrements audio

Tailles de miniatures par contexte :

Contexte	Taille thumbnail
Produit catalogue shopping	150 × 150 px (carré, centré)
Note (vignette liste)	300 × 300 px (carré, centré)
Pièce jointe (aperçu inline)	400 × 300 px (paysage, centré)

Les miniatures sont toujours servies pour les vues liste/grille. L'original n'est chargé qu'à la demande (plein écran, zoom). Formats audio acceptés : WebM, M4A.

2.4 MCP Server

Intégré dans FastAPI sur /mcp (protocole SSE). Expose les outils suivants aux agents IA (Hermes, Claude, etc.) :

Outil	Description
get_todos()	Retourne les tâches urgentes / en cours
add_todo(title, due_date)	Crée une tâche
get_shopping_list()	Retourne la liste de courses active
add_shopping_item(name, category)	Ajoute un article à la liste active
search_notes(query)	Recherche full-text dans les notes
add_note(title, content, tags)	Crée une note

---

3. Schéma de base de données

3.1 Schema shopping

shopping.products — Catalogue global

Colonne	Type	Description
id	UUID PK
name	VARCHAR(150)	Nom produit
brand	VARCHAR(100)	Marque
category	VARCHAR(50)	Rayon magasin (tri in-store)
image_path	VARCHAR(255)	Chemin original /uploads/images/originals/
thumbnail_path	VARCHAR(255)	Chemin miniature /uploads/images/thumbnails/
default_unit	VARCHAR(20)	kg / L / unité
barcode	VARCHAR(50)	Code-barres (scan futur)
frequency_score	INT DEFAULT 0	Score d'habitude (suggestions auto)
owner_id	UUID NULL	Prévu multi-user
created_at	TIMESTAMPTZ

Catégories produits (tri rayon en magasin) : Fruits · Légumes · Viandes · Charcuterie · Poissons · Produits laitiers · Boulangerie · Épicerie salée · Épicerie sucrée · Condiments · Boissons · Entretien · Pharmacie · Animaux · Carburant · Électronique · Divers

Magasins pré-configurés (seed) : Lidl · Intermarché · Super U · Gamm Vert · Weldom · Cosi · Bricocash · Tinel · Marie Blachère

Données de démarrage : 113 produits dans backend/app/data/seed_products.json, 9 magasins dans seed_stores.json — chargés automatiquement au premier démarrage.

shopping.stores — Magasins

Colonne	Type	Description
id	UUID PK
name	VARCHAR(100)	Ex: Lidl, Carrefour
location	TEXT	Adresse ou coordonnées GPS
owner_id	UUID NULL

shopping.price_history — Historique des prix

Colonne	Type	Description
id	UUID PK
product_id	UUID → products
store_id	UUID → stores NULL
price	NUMERIC(8,2)	Prix relevé
unit	VARCHAR(20)	kg / L / unité
quantity	NUMERIC(8,3)	Quantité associée
source	VARCHAR(20)	manual / ocr_tag / ocr_receipt
recorded_at	TIMESTAMPTZ

shopping.lists — Listes de courses

Colonne	Type	Description
id	UUID PK
name	VARCHAR(100)	Ex: "Semaine du 26 mai"
store_id	UUID NULL	Magasin cible
week_date	DATE	Date de la semaine cible
status	VARCHAR(20)	draft / active / done
owner_id	UUID NULL
created_at	TIMESTAMPTZ

shopping.list_items — Articles dans une liste

Colonne	Type	Description
id	UUID PK
list_id	UUID → lists
product_id	UUID → products NULL	Lié au catalogue (optionnel)
custom_name	VARCHAR(150)	Si article hors catalogue
quantity	NUMERIC(8,3)
unit	VARCHAR(20)
is_checked	BOOLEAN DEFAULT FALSE	Coché en magasin
price_recorded	NUMERIC(8,2)	Prix relevé pendant les courses
carried_over	BOOLEAN DEFAULT FALSE	Reporté depuis la semaine précédente
sort_order	INT	Tri par rayon/catégorie

3.2 Schema todos

todos.items

Colonne	Type	Description
id	UUID PK
title	VARCHAR(255)
body	TEXT	Texte libre
url	TEXT	Lien optionnel
domain	VARCHAR(50)	Voir liste des domaines
category	VARCHAR(50)	Sous-catégorie libre
tags	VARCHAR(50)[]	Array · index GIN
status	VARCHAR(20)	pending / done / cancelled
priority	VARCHAR(10)	low / medium / high
due_date	TIMESTAMPTZ	Date objectif
postponed_count	INT DEFAULT 0	Nombre de reports
created_at	TIMESTAMPTZ DEFAULT NOW()	Auto
updated_at	TIMESTAMPTZ
owner_id	UUID NULL

Domaines disponibles : informatique · diy · electronique · domotique · bricolage · jardin · cuisine · voyage · animaux

3.3 Schema notes

notes.items

Colonne	Type	Description
id	UUID PK
title	VARCHAR(255)	Optionnel
content	TEXT NOT NULL	Texte de la note
category	VARCHAR(50)
tags	VARCHAR(50)[]	Index GIN
gps_lat	NUMERIC(10,7)	Latitude GPS
gps_lon	NUMERIC(10,7)	Longitude GPS
metadata	JSONB	Paires clé/valeur libres (référence, magasin…)
created_at	TIMESTAMPTZ DEFAULT NOW()
owner_id	UUID NULL

Index : GIN(tags) + GIN(to_tsvector('french', title || ' ' || content)) (recherche full-text)

notes.attachments

Colonne	Type	Description
id	UUID PK
note_id	UUID → items
file_path	VARCHAR(255)	Chemin original /uploads/images/originals/
thumbnail_path	VARCHAR(255)	Chemin miniature (NULL si audio)
file_type	VARCHAR(20)	image / audio
original_name	VARCHAR(255)
created_at	TIMESTAMPTZ

---

4. Modules fonctionnels

4.1 Module Shopping — Liste de courses

Principe fondamental — ne jamais bloquer

L'objectif principal est simple : créer une liste en début de semaine, cocher les articles pendant les courses. Toutes les autres fonctionnalités (prix, OCR, stats, suggestions automatiques) sont optionnelles et n'apparaissent jamais dans le chemin principal. Un utilisateur qui ignore tout ça doit pouvoir utiliser l'app sans friction.

Concept général

La liste de courses est générée à partir du catalogue global de produits. Le frequency_score de chaque produit augmente à chaque achat — ce score alimente les suggestions automatiques de la semaine. L'utilisateur valide/modifie/complète la liste avant de partir en courses.

Les articles non cochés à la fin des courses sont automatiquement reportés (carried_over = true) dans la liste de la semaine suivante.

La saisie de prix est toujours optionnelle — le champ prix est discret, accessible d'un tap long ou d'un bouton secondaire, jamais dans le chemin de cocher un article.

Interface mobile (priorité)

• Création de liste : interface ultra-simple — picker de la semaine, suggestion automatique des produits habituels (top frequency_score), ajout rapide d'un produit (recherche dans le catalogue ou création à la volée)
• Mode courses (liste active) :
  • Grands boutons tactiles (min 48px)
  • Articles triés par rayon/catégorie
  • Tap pour cocher un article
  • Swipe gauche → supprimer de la liste
  • Champ prix rapide au tap (clavier numérique)
  • Wake Lock API : l'écran ne se verrouille pas pendant les courses
  • Bouton "Terminer les courses" → génère la liste suivante avec les articles non cochés

Interface laptop (complète)

• Vue tableau avec filtre par magasin, catégorie, statut
• Gestion du catalogue global de produits (CRUD complet)
• Gestion des magasins
• Graphiques d'évolution des prix par produit
• Export CSV de l'historique des prix

Module OCR (service Docker isolé, partagé entre tous les modules)

Le service OCR tourne dans son propre conteneur Docker (ocr:8001). Il est utilisable par tous les modules de l'application via l'endpoint unifié POST /api/ocr/extract du backend.

Module	Usage OCR
Shopping	Lecture étiquette prix en rayon → pré-remplissage prix
Shopping	Lecture ticket de caisse → réconciliation finale liste
Notes	Extraction texte depuis une photo (photo de document, panneau, référence)
Futur	Tout import photo dans l'application

Le module OCR est toujours optionnel : si le service est arrêté, les autres fonctionnalités de l'app ne sont pas impactées. Backend : Tesseract (local). Fallback possible : Ollama Vision (Hermes) en remplaçant simplement le service ocr dans le Docker Compose.

Suivi des prix

Chaque prix saisi (manuel, OCR étiquette ou OCR ticket) alimente price_history. Sur laptop, un graphique en courbe par produit montre l'évolution du prix dans le temps, par magasin.

4.2 Module Notes / Listes diverses

Saisie rapide de notes avec support multimédia et géolocalisation.

Champs :

• Titre (optionnel)
• Contenu texte libre (saisie rapide)
• Date (auto à la création, modifiable)
• Catégorie
• Tags (multi-valeurs, autocomplétion)
• Photo(s) : capture directe via Camera API ou import depuis galerie. Compression WebP avant upload
• Audio : enregistrement via MediaRecorder API. Format WebM/M4A
• GPS : bouton "Localiser" → Geolocation API → stocke lat/lon, affiche adresse via reverse geocoding (optionnel)
• Métadonnées libres : paires clé/valeur (ex: "Référence: X12-34", "Magasin: Brico Dépôt")

Recherche : full-text PostgreSQL en français sur titre + contenu + métadonnées. Filtres par catégorie, tags, présence de photo/audio/GPS.

4.3 Module Todos

Gestion de tâches classées par domaine.

Champs :

• Titre
• Texte libre (description)
• URL (lien externe optionnel)
• Domaine (liste fermée : voir section 3.2)
• Catégorie (libre)
• Tags (multi-valeurs)
• Statut : pending / done / cancelled
• Priorité : low / medium / high
• Date de création (auto)
• Date objectif (due_date)
• Compteur de reports (postponed_count)

Interface mobile : ajout rapide en 1 clic, vue liste épurée, actions swipe (reporter / terminer). Boutons "Reporter d'1 jour", "Reporter à la semaine prochaine".

Interface laptop : vue complète avec filtres multi-critères (domaine, statut, priorité, tags), tri, recherche textuelle.

---

5. Module scan code-barres / QR code

Fonctionnement

• Librairie JS zxing-js (open-source, cross-platform) intégrée dans le frontend
• Accès via le flux Camera API (pas de capture photo — lecture en temps réel)
• Fonctionne sur iOS Safari et Android Chrome
• Déclenché par un bouton 📷 "Scanner" dans le formulaire d'ajout de produit

Flux de résolution produit

Scan code-barres (EAN-13 / QR)
  → service product-search : GET /lookup?barcode={code}
    → 1. OpenFoodFacts API (base ~3M produits alimentaires)
       → trouvé : nom, marque, catégorie, image → auto-remplit le formulaire
    → 2. Si pas trouvé : retourne vide → saisie manuelle
       → enrichissement optionnel via recherche texte + SearXNG (laptop uniquement)

Service product-search (Docker)

API Python légère qui centralise :

• GET /lookup?barcode={code} → OpenFoodFacts par code-barres
• GET /search?q={nom} → OpenFoodFacts par nom de produit
• GET /image-search?q={nom} → SearXNG image search (fallback, laptop uniquement)

Le backend FastAPI expose ces fonctionnalités via /api/products/lookup, /api/products/search, /api/products/image-search.

Service searxng (Docker)

Instance SearXNG auto-hébergée, utilisée exclusivement pour la recherche d'images de produits non trouvés dans OpenFoodFacts. Accessible uniquement depuis l'interface laptop lors de l'enrichissement du catalogue. Non exposé publiquement via NPM.

---

6. Capacités natives smartphone (PWA)

API navigateur	Usage
Camera API	Capture photo directe (notes, OCR, produits)
MediaRecorder API	Enregistrement audio (notes vocales)
Geolocation API	Localisation GPS sur les notes
Wake Lock API	Écran actif pendant les courses
Web Share API	Partage de notes/listes vers autres apps
Liens webcal://	Abonnement calendrier natif iOS/Android (futur)

---

7. Design system

Le design system Gruvbox seventies est intégré dès le départ.

• Fichiers : design_system/tokens/tokens.css · design_system/components/ui-kit.jsx
• Thème : dark par défaut, light disponible via data-theme
• Palette : orange brûlé #fe8019 (accent), fond brun #2a231d, texte #f2e5c7
• 14 composants React disponibles (Button, IconButton, Toggle, StatusLed, BatteryGauge, RadialGauge, Popup, TreeNav, Sparkline, LineChart, Icon…)
• Fonts : Inter (UI) · JetBrains Mono (données) · Share Tech Mono (terminal/logs)
• Règles absolues : jamais de hex en dur, toujours var(--token), data-theme obligatoire sur un parent

---

8. Interface utilisateur — principes

Mobile-first

• Touch target minimum : 48px
• Composants d'action accessibles en 1 main
• Swipe sur les listes (reporter, terminer, supprimer)
• Chargement hors-ligne via Service Worker (cache assets + données critiques)
• Feedback haptique si disponible

Distinction mobile / laptop

Certains modules ont deux pages dédiées selon la taille d'écran :

Module	Mobile	Laptop
Shopping	Création liste simple + mode courses	Catalogue produits + gestion magasins + graphiques prix
Todos	Ajout rapide + liste swipeable	Tableau filtrable multi-critères
Notes	Saisie rapide + media capture	Liste complète + recherche avancée

---

9. Hors scope initial (Phase 1-5)

• Authentification multi-utilisateurs (Phase 7)
• Google Calendar / CalDAV (Phase 6)
• Kanban / Gitea webhooks (Phase 8)
• Home Assistant (Phase 8)
• Analyse frigo par Vision LLM / Hermes (Phase 9)
• Scan code-barres produits