# famapp Self-hosted family coordination web app for Matt and his wife. Replaces a commercial family app with a shared calendar, shopping/task lists, and notes/reminders. Designed to be **deliberately extensible** — Matt expects to bolt on niche features over time, so the architecture treats every feature as a module. This file is the canonical brief. Read it at the start of every session before making changes. Sub-task briefs in [`docs/tasks/`](docs/tasks/) reference this file; do not duplicate its contents there. --- ## Goals - Replace current family app: shared calendar, shopping list, task list, notes/reminders. - Self-hosted on Matt's home server, accessible from outside the house with auth. - Wife-friendly: installable PWA, passkey/SSO login, no extra apps to install for notifications. - "Share anything" — most entities can produce a temporary public link for outsiders. - Architecture optimized for adding many small features later without core changes. --- ## Stack (decided) | Layer | Choice | Notes | | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Frontend + backend | Next.js 15 App Router + TypeScript | Single Node process, server actions for mutations | | UI | Tailwind + shadcn/ui | | | DB | Postgres 16 | Dedicated container per app (Matt's rule) | | ORM | Drizzle | Lightweight, SQL-friendly, good for evolving schema | | Auth/SSO | **Authentik** at `auth.ginnoir.com` | Picked over Pocket-ID because it ships forward-auth (Proxy Provider) for the rest of Matt's stack (Sonarr/Radarr/Prowlarr/NZBGet/qBittorrent/Tautulli/Overseerr/FreshRSS/ntfy) which has no native OIDC. famapp itself uses OIDC. | | Push | Web Push (VAPID) | Works in installed PWAs incl. iOS Safari 16.4+. ntfy stays optional. | | Realtime | Postgres `LISTEN/NOTIFY` → SSE | Simpler than WebSockets, fine for two users | | Reverse proxy | Caddy (existing) | `fam.ginnoir.com` → famapp:3000, `auth.ginnoir.com` → authentik | | Package manager | pnpm | Fast, content-addressed store, strict deps | | Runtime | Node 22 LTS | In `node:22-alpine` container | | Host | Ubuntu Server 24.04 x64, Docker + Compose | Existing self-host stack | Domain: `fam.ginnoir.com`. SSO: `auth.ginnoir.com`. --- ## Architecture: extensibility-first Every feature is a self-contained **module** under `src/modules//`. A module declares its tables, routes, dashboard contributions, quick-add actions, and supported share/reminder/search behaviors via a manifest. Core services (sharing, push, activity log, search, reminders) operate generically against any registered entity — adding a new module should not require touching core code. ``` src/ modules/ _core/ # auth, household, sharing, push, activity log, reminders calendar/ schema.ts # drizzle tables server/ # server actions + queries components/ routes.ts # registers /calendar pages + API dashboard.tsx # widget contributed to dashboard manifest.ts # name, icon, nav, entity types, share/reminder handlers lists/ notes/ app/ # Next.js routes — thin, mounts modules lib/ ``` ### Core primitives every module gets - **Entity registry.** Modules declare entity types; share-link, activity log, search, reminders all work against any registered entity. - **Dashboard widget registry.** Every widget is uniformly configurable (no singleton/parameterized split) and reusable — each placement on a dashboard is an independent instance with its own config. Each user has multiple dashboards; the active dashboard composes whatever widgets they've placed. - **Quick-add registry.** Modules register quick actions for the dashboard's `+` menu. - **Share-link service.** `createShareLink(entityType, entityId, { expiresAt, capabilities })` → `fam.ginnoir.com/s/`. Generic. - **Notification bus.** `notify(userId, { title, body, url })` fans out to web push + in-app + (optional) ntfy. - **Permissions.** Household-scoped by default. Share-tokens grant scoped read/write per entity. - **Feature flags.** Env/db-driven for staging experiments. **Rule for contributors (including future Sonnet sessions):** if a feature requires a change to `_core` to support a new entity type, that's a smell — extend the registry instead. --- ## Data model (v1) - `users`, `households`, `household_members` - `calendars` — name, color, owner_id, visibility (`private` | `household`). First-class entity; users create as many as they want, each independently shareable via the share-link service. - `calendar_events` — `calendar_id` fk, title, start, end, all_day, location, notes, owner. `rrule` text column reserved (no recurrence in v1). `external_source`/`external_id` nullable for future Google/Apple sync. - `lists` (type text — not enum, to allow extension), `list_items` - `notes` — title, body, pinned, remind_at - `dashboards` — per-user named dashboards (any user can have many), `layout` jsonb of placed widgets `[{ widgetId, config, x, y, w, h }]`. - `share_links` — entity_type, entity_id, token, capabilities jsonb, expires_at - `activity_log` — entity_type, entity_id, actor, action, payload jsonb - `push_subscriptions` - `reminders` — entity_type, entity_id, fire_at, channel. Generic; used by notes/events/anything. All household-scoped entity tables include `household_id`. Sub-entities (`calendar_events`, `list_items`) inherit scope via their parent. All reads/mutations are gated by the caller's household membership and, where relevant, per-entity visibility (e.g. private calendars). --- ## Pages (v1) - `/` Dashboard — today + next 3 days events, top of shopping list, open tasks, pinned notes, recent activity, quick-add `+` - `/calendar` — month/week/day, drag-create - `/lists/shopping`, `/lists/tasks` — defaults; create more - `/notes` - `/s/` — public share viewer - `/settings` — household, push toggles, share-link management --- ## Deploy shape ```yaml # compose.yaml (sketch — final lives in /deploy) services: famapp: # node:22-alpine, Next.js famapp-db: # postgres:16 authentik-server: authentik-worker: authentik-db: # postgres:16 (separate per Matt's rule) authentik-redis: ``` Caddy: `fam.ginnoir.com` → `famapp:3000`. `auth.ginnoir.com` → `authentik-server:9000`. Backups: nightly `pg_dump` to a host volume. Out of scope for phase 1 but reserve the cron slot. --- ## Build phases 1. **Scaffold** — repo init, Next.js + Drizzle + Tailwind + shadcn, module loader, compose stack, Caddy snippet, Authentik wired up, seeded household with both users. 2. **Core modules** — calendar, lists, notes (CRUD only). 3. **Dashboard + quick-add + activity log.** 4. **Sharing** — share-link service + `/s/` viewer. 5. **Push notifications + reminders.** 6. **PWA polish** — manifest, icons, offline shell, install prompt. 7. **Hardening** — backups (pg_dump cron), rate limiting on share links, logging. Tasks for each phase live in [`docs/tasks/`](docs/tasks/). Sub-sessions should pick up a task file, follow its scope, and stop at its acceptance criteria. --- ## Conventions - **TypeScript strict.** No `any` without a written reason. - **Server actions** for mutations; route handlers only for webhooks/SSE/share-link viewer. - **Drizzle migrations** committed under `drizzle/`. Never edit a shipped migration — add a new one. - **No comments** unless the _why_ is non-obvious. Names should carry intent. - **Module isolation.** A module imports from `_core` and `lib/` only — never from a sibling module. - **One module = one PR/commit boundary** when possible. - **Tests:** Vitest for units (where it pays off), Playwright for one happy-path E2E per module. Don't write tests for trivial CRUD. - **Secrets** via `.env` (gitignored) and `.env.example` (committed, no values). --- ## Out of scope for v1 (do not build) - ICS export / Google / Apple / Outlook calendar sync (data model leaves room) - Recurrence editor (column reserved, no UI) - Native iOS/Android app (PWA only; architecture must not preclude it) - Migration from any existing app (starting fresh) - Forward-auth wiring for the rest of Matt's stack (Authentik is installed; wiring the \*arr apps is a separate later task) - Multi-tenant / multi-household (schema has `household_id` but UI is single-household) --- ## Where things live - **This brief:** `CLAUDE.md` - **Task briefs for sub-sessions:** `docs/tasks/NN-name.md` - **Architecture decisions worth preserving:** `docs/decisions/NNNN-title.md` (lightweight ADR — only when a non-obvious choice is made) - **App code:** `src/` - **Drizzle migrations:** `drizzle/` - **Deploy:** `deploy/` (compose.yaml, Caddyfile snippet, Authentik bootstrap) - **Memory (cross-session):** `C:\Users\MattC\.claude\projects\C--Users-MattC-Documents-famapp\memory\`