famdone/ARCHITECTURE.md

# FamChore v2 — Architecture & Developer Reference

## Overview

Multi-tenant chore tracking SaaS. Families ("fams") are isolated tenant groups. Admins (parents) authenticate via email/password; members (children) join via invite OTP and get a server-derived password. No `members` collection — everyone is a `users` row scoped by `famId`.

**Source of truth:** `AGENTS.md` is the living reference. This doc captures the architecture.

---

## 1. Stack

| Component | Role | Deploy | Port |
|---|---|---|---|
| SvelteKit | SSR frontend, all UI + Stripe server routes | Coolify Docker (nginx) | :2080 internal, :3001 external |
| Hono proxy | data layer (`/api/*`); CRON | Same container, proxied via nginx `/api/*` | :3456 internal |
| PocketBase | DB, auth, realtime, storage, Admin UI | Coolify service (pb.chores.app.com) | :8090 |
| Stripe | subscriptions (in SvelteKit, NOT Hono) | — | — |

### Deployment Topology

```
chores.app.com ────┬──► nginx (:3001)
                    │      ├── /*    ──► SvelteKit (:2080)
                    │      └── /api/* ──► Hono proxy (:3456)
                    │
pb.chores.app.com ──► PocketBase (:8090)
                     │      Admin UI at /_
                     │      Volume: /pb_data (persistence + backups)
                     │
stripe.com ─────────► SvelteKit /account/webhook
```

---

## 2. Auth Model

### 2.1 Roles & Methods

| Role | Auth | Session | PB Entity |
|---|---|---|---|
| **Admin (parent)** | PB email + password | 24hr JWT `pb_token` cookie | `users` (role `parent`) |
| **Member (child)** | Invite OTP + server-derived password | httpOnly `pb_token` cookie | `users` (role `child`) |
| **Superuser** | PB `_superusers` (server-side only) | — | `_superusers` |

### 2.2 Details

- **Admins** are `users` (role `parent`). Login via email/password → httpOnly `pb_token` cookie `{ id, name, username, role: "parent", famId, color }`.
- **Members** are `users` (role `child`); PB `username` = `{famSlug}:{handle}` (globally-unique; `handle` = whitespace-free lowercase name), URL segment = `handleOf(username)`, `name` = display name. Password is **derived** server-side (`MEMBER_SECRET + famSlug + handle`). Join gated by a 20-min OTP in `otp`, then `authWithPassword`. Same httpOnly `pb_token` cookie. No `members` collection.
- **Superuser** used only server-side by `pb-admin.ts` for cross-family queries (`/admin`) and OTP/signup writes.
- Layout `[fam]/+layout.server.ts` derives `isParent`/`role` centrally from the session. `pb_token` is httpOnly, so the browser PB SDK is seeded from `page.data.pbToken` via `initPb(token)` in `onMount`.

### 2.3 PB Auth Rules

Every tenant-scoped collection has `famId` and enforces `famId = @request.auth.famId`; family-scoped collections have public `listRule`/`viewRule` so reads/subscribes work for both roles. Superuser bypasses via admin API.

---

## 3. Data Model (PB collections, all scoped by `famId`)

- `users` — auth collection; famId, role (`parent`|`child`), username (`{famSlug}:{handle}`), name, color, email (admin only)
- `otp` — famId, userId, otp, updatedAt (OTP gate for child join; display colour on `users.color`)
- `fams` — name, slug, stripeCustomerId, featureFlags
- `chore_templates` — famId, name, defaultValue, defaultFrequency
- `assigned_chores` — famId, userId, templateId, frequency, value
- `completions` — famId, userId, assignedChoreId, date
- `weekly_history` — famId, userId, weekStart, pointsEarned, moneyEarned
- `rewards` — famId, userId, source, label, value, claimed, claimedAt, claimable, settleDate
- `monthly_bonuses` — famId, month, prizeType, prizeValue, winnerUserId
- `settings` — famId, pointsThreshold, weeklyBonus, webhookUrl

> **Schema/migrations:** `shared/pb/schema.ts` (`SCHEMA_PLAN`) is the single source of truth for base collections. `frontend/src/lib/server/migrate.ts` bootstraps a fresh/wiped PB (idempotent). The native `users` auth fields/rules + superuser-only `otp` are applied in `migrate.ts` (`ensureUsers`/`ensureOtp`). Data is disposable — schema change = update `SCHEMA_PLAN` + wipe PB + reboot.

---

## 4. Routes

### SvelteKit

```
/                            Landing page (SaaS marketing)
/admin                       Platform super-admin stats dashboard
/login · /logout             Parent login / logout
/signup                      Parent + family signup
/{famSlug}/join/{username}   Member invite (OTP join), auto-fills from ?code=
/{fam}                       Fam dashboard
/{fam}/{username}            Parent → admin overview, Child → member kanban
/{fam}/{username}/chores     Chore templates & assignment grid
/{fam}/{username}/ledger     Rewards / chores / todos ledger
/{fam}/{username}/bonuses    Bonus configs & evaluation
/{fam}/{username}/preferences  User preferences
/{fam}/{username}/settings   Family admin settings (parent only) — Stripe connect/manage + pause
/account                     Account/billing — payment setup & subscription management
/subscriptions              3-tier plan page (trial | monthly | yearly), access via settings
/account/webhook             Stripe webhook handler (server route)
/api/*                       Hono proxy (data layer; CRON not implemented)
```

---

## 5. Data Flow

### 5.1 Reads (both roles)

- `famStore.init()` fetches all collections via PB SDK, authenticated via the seeded `pb_token`. `.subscribe()` works for both roles.
- TopNav season pills read from `famStore.seasons` (reactive).

### 5.2 Writes

- **Chore toggle:** Browser → Hono proxy → PB (member auth via `Authorization: Bearer <pb_token>`).
- **Admin CRUD:** Form actions / `hono.admin.*` → Hono proxy → PB (admin JWT via `sessionHeaders`).
- **Member updates:** Browser → Hono proxy → PB (`Bearer <pb_token>`).
- **Reward creation:** after completion toggle, Hono proxy creates reward if threshold met.
- **Weekly settlement:** NOT via CRON — manual `complete-week` action or `simulateEow` preview in settings. `/api/weekly-cron` (Coolify) not implemented.
- **Stripe:** SvelteKit server routes `/account` + `/account/webhook` (frontend app, NOT Hono).
- **WhatsApp:** not implemented.

### 5.3 Stripe Subscription (embedded Checkout)

```
Parent picks a tier on /subscriptions (trial | monthly | yearly)
  → SvelteKit server action (subscriptions) creates Embedded Checkout Session
      createEmbeddedCheckoutSession() → ui_mode: "embedded" → client_secret
  → returns { clientSecret } to the browser
  → @stripe/stripe-js createEmbeddedCheckoutPage({ clientSecret }) mounts in-page
  → Parent completes payment inside the embedded Stripe page
  → Stripe sends checkout.session.completed → SvelteKit /account/webhook
      handleStripeEvent() → pbAdmin.update fams.stripeCustomerId + active = true
  → Subsequent customer.subscription.* webhooks keep fams.active in sync
  → Parent returns to /account?checkout=return
```

Pause/stop via Stripe Customer Portal (from `/account`) or the pause toggle (writes `fams.active` directly).

### 5.3.1 Payments architecture

```
┌──────────────────────────────────────────  SVELTEKIT APP  ──────────────────────────────────────────┐
│                                                                                                      │
│  Browser                                                                                             │
│  ┌──────────────────────────────┐   POST ?/checkout    ┌─────────────────────────────────────────┐  │
│  │  /subscriptions (+page.svelte)│ ───────────────────► │  subscriptions/+page.server.ts (action) │  │
│  │  • tier cards                │                       │  • resolves famId + parent email (PB)   │  │
│  │  • createEmbeddedCheckoutPage│ ◄─── clientSecret ─── │  • createEmbeddedCheckoutSession()      │  │
│  │  • mounts embedded Stripe UI │                       └───────────────┬─────────────────────────┘  │
│  └──────────────┬───────────────┘                                       │  stripe SDK (secret)        │
│                 │ createEmbeddedCheckoutPage(clientSecret)              ▼                             │
│                 ▼                                        ┌─────────────────────────────┐            │
│  ┌──────────────────────────────┐                        │   STRIPE API                │            │
│  │  Embedded Checkout (Stripe   │  card + pay            │   checkout.sessions.create  │            │
│  │  hosted iframe, in-page)     │ ───────────────────►  │   (ui_mode: embedded)        │            │
│  └──────────────────────────────┘                        └──────────────┬──────────────┘            │
│                                                                         │ webhook events              │
│                                                                         ▼                            │
│  ┌──────────────────────────────────────────────────────────────────────────────────────────────┐   │
│  │  /account/webhook (+server.ts)                                                               │   │
│  │  • verify stripe-signature (CLI secret in dev, dashboard in prod)                           │   │
│  │  • handleStripeEvent()  →  stripe-events.ts                                                 │   │
│  │    └ checkout.session.completed  → fams.stripeCustomerId + active = true                    │   │
│  │    └ customer.subscription.*     → fams.active  (sync by customer id)                       │   │
│  └──────────────────────────────────────────────────────┬─────────────────────────────────────┘   │
│                                                         │ pbAdmin (superuser)                     │
└─────────────────────────────────────────────────────────┼─────────────────────────────────────────┘
                                                          ▼
                                                ┌────────────────────┐
                                                │   POCKETBASE        │
                                                │   fams.stripeCustomerId │
                                                │   fams.active (bool)    │
                                                └────────────────────┘

Management:
  /account (+page.server.ts)
    • billing action → createBillingPortalSession(customerId) → Stripe Customer Portal
      (update card, cancel / reactivate subscription)
    • togglePause action → pbAdmin.update fams.active (hard pause, independent of Stripe)

Dev-only:
  stripe CLI:  stripe listen -e ... --forward-to http://127.0.0.1:2080/account/webhook
               (sets STRIPE_CLI_WEBHOOK_SECRET for local signature verification)
```

**Key decisions**
- **Payments live in SvelteKit, not Hono** — the app already owns SSR + server actions; Hono stays a pure data layer. Stripe secret never reaches the client.
- **`fams.active`** is the single app-level gate: webhooks (subscription lifecycle) and the pause toggle both write it. It disables interactions + payments when `false`.
- **Embedded Checkout** (in-page, no redirect) via `createEmbeddedCheckoutPage` — needs a same-origin `return_url`; subscriptions require a `customer` (created with `customer_creation: 'always'` + `customer_email` if the fam has none yet).
- **Trial** is app-side: a code maps to `trial_period_days` on the subscription; the trial Stripe price is a `$0` plan. Real-world codes should move to a PB collection.
- **Webhook secrets** — `STRIPE_CLI_WEBHOOK_SECRET` (dev) overrides `STRIPE_WEBHOOK_SECRET` (prod/dashboard); `verifyStripeEvent` picks the CLI one when set. Dev testing uses the Stripe CLI (`stripe listen --forward-to http://127.0.0.1:2080/account/webhook`) which forwards real signed events; a real checkout carries the `famId` and drives the DB write end-to-end.

### 5.4 UI reactivity

- Svelte `$state` / `$derived` / `$effect`.
- PB SDK `.subscribe()` for realtime multi-user sync (public reads → both roles).
- `famStore.applyRecord()` for instant optimistic feedback.
- **Rule:** if data should update via SSE, use `$derived` (not `$state` — frozen snapshot). Only high-frequency member actions use `$state` + optimistic `applyRecord`.

---

## 6. Project Structure

```
/ (root)
  /shared/pb/schema.ts       SCHEMA_PLAN — source of truth for base collections
  /frontend                  SvelteKit app (:2080)
    /src/env.ts              declareEnvVars — client/server env
    /src/lib/server          pb-admin, migrate.ts, services, hono.ts (sessionHeaders)
    /src/lib/client          api.ts (memberApi), stores (famStore)
    /src/lib/components      UI components (re-exported from index.ts)
    /src/routes              SvelteKit file-based routing (incl /account, /subscriptions)
  /proxy                     Hono proxy (:3456)
  /docker                    Dockerfile (prod multi-stage + nginx), Dockerfile.dev (PB)
  /config.ts                 dev/build-time shared config (ports)
  /MEMORY.md                 decisions log
  AGENTS.md                  AI reference
  ARCHITECTURE.md            This document
```

---

## 7. Environment Variables

Env vars declared in `frontend/src/env.ts` via `defineEnvVars` (`@sveltejs/kit/hooks`). Only `{ public: true }` are exposed client-side via `$app/env/public`; server-only via `$app/env/private`.

- `FRONTEND_PORT`, `PROXY_PORT`, `PB_PORT`
- `PB_EMAIL`, `PB_PASSWORD` (PB superuser, server-only)
- `DEBUG_RECORD_ID`
- `STRIPE_SECRET_KEY` (server-only)
- `DONATION_MODAL_INTERVAL`
- `SERVER_IP` (public, dev)

Values come from root `.env` (symlinked at `frontend/.env -> ../.env`). `.env.example` is the committed template. Ports also tracked in root `config.ts`.

---

## 8. Key Conventions

- **`famId` on every query** — PB auth rules enforce `famId = @request.auth.famId`; superuser bypasses.
- **Member → Proxy (server/browser):** `memberApi.*` in `$lib/client/api.ts`; `BASE_URL` resolves to Hono port on server, empty in browser (Vite proxies `/api/*`).
- **Admin → Proxy:** `hono.admin.*` in `$lib/server/hono.ts` — `sessionHeaders(event)` (server-only, requires `RequestEvent`).
- **Child passwords derived** — `MEMBER_SECRET + famSlug + username`; join gate is a transient OTP. Never log raw tokens/secrets.
- **`$page`** — from `$app/state` (not `$app/stores`); no `$` prefix.
- **Dates** — user-facing via `formatDDMMYY()` (compact `040826`); human-readable due dates use `formatShortDate()`. Never render raw `YYYY-MM-DD`.
- **UI shell** — `[fam]/+layout.svelte` (Sidebar, TopNav, Footer); `ViewHeader` + `CardGrid`/`Card` micro-layout; `Button` for CTAs; icons as SVG strings in `lib/components/icons.ts`.
- **Reactivity** — never `$effect` to sync local state from famStore; use `$derived` for SSE-reactive data; `$state` + `applyRecord` only for optimistic member toggles.
- **Dev servers** — never start your own; reuse running proxy (`192.168.1.225:3456`) + frontend (`localhost:2080`).

---

## 9. Open / Deferred

- **WhatsApp notifications** — `NotificationService` plugin for the weekly CRON handler. Deferred.
- **Stripe payments** — flow not yet implemented. Only `fams.stripeCustomerId` + `settings.webhookUrl` exist. Building in SvelteKit `/account` + `/account/webhook`. Trial via codes (app-side validation + `trial_period_days`) — TBD.
- **Weekly CRON** (`/api/weekly-cron`, Coolify) — not implemented; settlement is manual via `complete-week`/`simulateEow`.