93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# 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 (`<html>` 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 `<Icon name="…">` 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 (`<IconButton>` 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
|