Files

T

gilles b87c96ceab chore: ajout .gitignore, CLAUDE.md, design system et docs Phase 2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-24 14:10:18 +02:00

4.8 KiB

Raw Blame History

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

Always use CSS variables — never hardcode hex colors. color: var(--accent) ✅, color: #fe8019 ❌
Always declare data-theme="dark|light" on a parent element (<html> or a wrapper)
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…)
Never use emoji or custom SVG for icons — use <Icon name="…"> with the mapped names
No hover effects on buttons/tiles (only 3D press on click via .interactive)
Always use tooltips on standalone icon buttons (<IconButton> requires label)
Three fonts only: var(--font-ui) (Inter, UI text), var(--font-mono) (JetBrains Mono, data/numbers), var(--font-terminal) (Share Tech Mono, logs/retro)
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)

Docker setup + PostgreSQL schemas + FastAPI auth + React PWA scaffold
Todos CRUD + Notes CRUD + mobile UI + full-text search (PostgreSQL FTS in French)
Shopping list (store mode + Wake Lock + frequency-based auto-fill + Hermes vision)
Calendar (CalDAV + Google OAuth2 sync worker)
MCP server + Gitea webhooks

4.8 KiB Raw Blame History