# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project: HomeHub HomeHub is a personal organization self-hosted PWA deployed via Docker Compose on Proxmox 9 (Debian 13). It targets heavy mobile usage with offline support. ## Architecture décidée Two competing architectures are documented. The **retained one** (from `Consignes de Développement App Self-hosted.md`) is: | Service | Stack | |---------|-------| | Frontend | React + Vite + TypeScript + Tailwind CSS (PWA) | | Backend | FastAPI (Python) — async, SQLAlchemy 2.0 | | Database | PostgreSQL 16 — multiple schemas (not multiple DBs) | | Queue/Cache | Redis | | Proxy | Traefik / OPNsense in front | The alternative modular approach (Vikunja + PocketBase + Keeper.sh + SvelteKit in the brainstorming doc) was **not retained**. ### Backend structure (FastAPI) ``` backend/ ├── app/ │ ├── api/ # Endpoints split by domain: auth, todos, shopping, notes, calendar, mcp │ ├── core/ # Config, security, DB (SQLAlchemy async) │ ├── models/ # SQLAlchemy models using PostgreSQL schemas │ ├── schemas/ # Pydantic validation schemas │ ├── services/ # Business logic (calendar sync, Hermes Vision integration) │ └── main.py ├── Dockerfile └── requirements.txt ``` ### PostgreSQL schemas One PostgreSQL instance, logical separation via schemas: `auth`, `todos`, `shopping`, `notes`, `kanban`. This allows cross-schema joins while simplifying backups (`pg_dump` once). ### Security - JWT authentication - CORS allowing local network `10.0.0.0/22` only ## Design System — Gruvbox seventies **All UI must use the design system files in `design_system/`.** Read `design_system/consigne_design_system.md` before writing any UI code. ### Absolute rules 1. **Always use CSS variables** — never hardcode hex colors. `color: var(--accent)` ✅, `color: #fe8019` ❌ 2. **Always declare `data-theme="dark|light"`** on a parent element (`` or a wrapper) 3. **Never reinvent existing components** — check `design_system/components/ui-kit.jsx` first (14 components: Button, IconButton, Toggle, Tooltip, StatusLed, BatteryGauge, RadialGauge, BigRadialGauge, Popup, TreeNav, Sparkline, LineChart, Icon…) 4. **Never use emoji or custom SVG** for icons — use `` with the mapped names 5. **No hover effects** on buttons/tiles (only 3D press on click via `.interactive`) 6. **Always use tooltips** on standalone icon buttons (`` requires `label`) 7. **Three fonts only**: `var(--font-ui)` (Inter, UI text), `var(--font-mono)` (JetBrains Mono, data/numbers), `var(--font-terminal)` (Share Tech Mono, logs/retro) 8. **Border radius**: tiles 10-12px, buttons 8px, pills 999px — never 24px+ ### Key CSS tokens - Backgrounds: `--bg-1` (app) → `--bg-2` (panels) → `--bg-3` (cards/tiles) → `--bg-4` (hover) → `--bg-5` (active) - Text: `--ink-1` (primary) → `--ink-2` → `--ink-3` (labels) → `--ink-4` (disabled) - Status: `--ok`, `--warn`, `--err`, `--info` - `className="glass"` or `"glass-strong"` handles card styling (backdrop-filter + shadow) ### Design system files - `design_system/tokens/tokens.css` — web CSS variables (dark + light) - `design_system/tokens/tokens.gnome.css` — GTK 4 / libadwaita overrides - `design_system/tokens/tokens.json` — generic format for Tailwind/Figma - `design_system/components/ui-kit.jsx` — all 14 React components - `design_system/examples/exemple-minimal.html` — reference demo ## Frontend PWA requirements - Configure `@vite-pwa/plugin` with aggressive asset caching for offline use - `manifest.json` with icons for iOS and Android - Show a clean "Offline" state in UI - Touch targets minimum 48px height (mobile-first) - Swipe gestures on todo/shopping lists (left to postpone, right to complete) - Wake Lock API on the shopping list active view (screen stays on in-store) ## Integrations - **Gitea**: `gitea.maison43.duckdns.org` — webhook endpoint `/api/webhooks/gitea` for issue/PR sync to Kanban - **Home Assistant**: `10.0.0.2:8123` — expose delayed task count as sensor via REST/MQTT - **Agent Hermes / Vision LLM**: `POST /api/shopping/analyze-fridge` — sends fridge photo to LLM for missing ingredient suggestions - **MCP server**: embedded in FastAPI — exposes `get_todos()`, `add_todo()`, `add_shopping_item()`, `search_notes()` tools - **CalDAV**: `/api/caldav/` for native iOS subscription - **Google Calendar**: OAuth2 per user + async background worker ## Development phases (reference) 1. Docker setup + PostgreSQL schemas + FastAPI auth + React PWA scaffold 2. Todos CRUD + Notes CRUD + mobile UI + full-text search (PostgreSQL FTS in French) 3. Shopping list (store mode + Wake Lock + frequency-based auto-fill + Hermes vision) 4. Calendar (CalDAV + Google OAuth2 sync worker) 5. MCP server + Gitea webhooks