# FamDone 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 services + Stripe server routes (`/api/*`) | Coolify Docker (nginx) | :2080 internal, :3001 external | | PocketBase | DB, auth, realtime, storage, Admin UI | Coolify service (pb.chores.app.com) | :8090 | | Stripe | subscriptions (SvelteKit server routes) | — | — | ### Deployment Topology ``` chores.app.com ────┬──► nginx (:3001) │ ├── /* ──► SvelteKit (:2080) │ └── /api/* ──► SvelteKit (:2080) │ pb.chores.app.com ──► PocketBase (:8090) │ Admin UI at /_ │ Volume: /pb_data (persistence + backups) │ stripe.com ─────────► SvelteKit /api/webhooks/stripe ``` --- ## 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`) - `accesscodes` — value (unique), name, duration, expiry, active, createdAt (superuser-only; platform access codes) - `platform` — label (`global` singleton), flags (json) — platform feature flags; public read (empty list/view rules), superuser-only writes. Loaded on every page via root `+layout.server.ts` as `page.data.platformFlags`; toggled from the `/admin` Platform Flags card (`debug` gates dev-only CTAs like settings "Revoke code"). Replaces the deprecated per-fam `fams.featureFlags`. - `fams` — name, slug, stripeCustomerId, paymentMode (`none`|`code`|`sub`|`canceled`), active, accessCodeId, accessCodeEnteredAt - `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 + the superuser-only `otp`/`accesscodes` and public-read `platform` collections are applied in `migrate.ts` (`ensureUsers`/`ensureOtp`/`ensureAccessCodes`/`ensurePlatform`); `ensureFamFields()` hardens existing installs with newer `fams` fields. 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 (wizard: fam → child → code → plan) /{fam}/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 /settings (Billing group) Subscription status, change plan, open billing portal /pricing 3-tier public plan page (trial | monthly | yearly), entry via settings or logged-out /api/webhooks/stripe Stripe webhook handler (server route) /api/* SvelteKit API endpoints (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 → SvelteKit `/api/completions/toggle` → PB (session cookie auth). - **Admin CRUD:** Form actions / `/api/admin/*` endpoints → PB via services; PB collection rules are the security boundary. - **Member updates:** Browser → SvelteKit `/api/*` routes → PB. - **Reward creation:** after completion toggle, service layer 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 `/pricing` + settings Billing actions + `/api/webhooks/stripe`. - **WhatsApp:** not implemented. ### 5.3 Stripe Subscription (embedded Checkout) ``` PUBLIC PRICING SIGNUP WIZARD AFTER ───────────── ───────────── ───── /pricing ── logged out ──► /signup?plan=X └─ logged in ──► embedded checkout (existing behavior) 1. fam create family + parent 2. child add child / skip 3. code "Have an access code?" ├─ apply valid ──► 5. done (fam active) └─ skip ─────────► 4. plan 4. plan PricingPlans component ├─ ?plan=X pre-highlights that tier ├─ pick tier ──► embedded checkout mounts INLINE └─ trial tier hidden (codes live at step 3) 5. done "Go to dashboard" webhook sets paymentMode=sub → overlay lifts ``` Webhook events (`/api/webhooks/stripe`) update `fams.stripeCustomerId`, `fams.active`, `fams.paymentMode` from subscription lifecycle. ### 5.3.1 Payments architecture ``` ┌────────────────────────────────────────── SVELTEKIT APP ──────────────────────────────────────────┐ │ │ │ Browser │ │ ┌──────────────────────────────┐ POST ?/choose ┌─────────────────────────────────────────┐ │ │ │ /pricing (+page.svelte) │ ───────────────────► │ pricing/+page.server.ts (action) │ │ │ │ • PricingPlans component │ │ • logged-out: redirect /signup?plan=X │ │ │ │ • createEmbeddedCheckoutPage │ ◄─── clientSecret ─── │ • logged-in: createEmbeddedCheckout... │ │ │ │ • 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_page) │ │ │ └──────────────────────────────┘ └──────────────┬──────────────┘ │ │ │ webhook events │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────────────────────────────┐ │ │ │ /api/webhooks/stripe (+server.ts) │ │ │ │ • verify stripe-signature (CLI secret in dev, dashboard in prod) │ │ │ │ • handleStripeEvent() → stripe-events.ts │ │ │ │ └ checkout.session.completed → fams.stripeCustomerId + active + paymentMode='sub' │ │ │ │ └ customer.subscription.* → fams.active + paymentMode (sync by customer id) │ │ │ │ └ customer.subscription.deleted → active=false + paymentMode='canceled' │ │ │ └──────────────────────────────────────────────────────┬─────────────────────────────────────┘ │ │ │ pbAdmin (superuser) │ └─────────────────────────────────────────────────────────┼─────────────────────────────────────────┘ ▼ ┌────────────────────┐ │ POCKETBASE │ │ fams.stripeCustomerId │ │ fams.active (bool) │ │ fams.paymentMode │ └────────────────────┘ SIGNUP WIZARD (inline checkout at step 4): /signup?plan=X 1. fam create family + parent (no code field) 2. child add child / skip 3. code "Have an access code?" → apply or skip 4. plan PricingPlans component (hideTrial), selecting a plan → ?/choose action → createEmbeddedCheckoutSession → mount embedded inline 5. done "Go to dashboard" — webhook flips paymentMode=sub, overlay lifts Management: Settings → Billing group (+page.server.ts ?/billingPortal) • createBillingPortalSession(customerId) → Stripe Customer Portal (update card, cancel / reactivate subscription; returns to /{fam}?checkout=return) Gating derives from fams.paymentMode alone (none = gated). No local pause flag. Dev-only: pnpm stripe:listen (root script) = stripe listen -e customer.subscription.updated,customer.subscription.deleted,checkout.session.completed --forward-to http://127.0.0.1:2080/api/webhooks/stripe (sets STRIPE_CLI_WEBHOOK_SECRET for local signature verification) Embedded Checkout needs a secure context (HTTPS or localhost). Over Tailscale/LAN HTTP the checkout iframe hangs silently — port-forward instead: ssh -L 2080:localhost:2080 ``` **Key decisions** - **Payments live in SvelteKit server routes** — the app owns SSR + server actions end-to-end. Stripe secret never reaches the client. - **`fams.paymentMode` + `fams.active`** gate the platform (see 5.3.2). Webhooks write `paymentMode`; `ensureFamAccess()` recomputes and persists `active` on every `[fam]` layout load. - **Embedded Checkout** (in-page, no redirect) via `createEmbeddedCheckoutPage` with `ui_mode: 'embedded_page'` (`'embedded'` is deprecated) — needs a same-origin `return_url`. No `customer_creation` (subscription mode only; Stripe auto-creates the customer from `customer_email`). - **Access codes are a real PB collection** (`accesscodes`, superuser-only) — entered at signup or via settings; replaces the earlier app-side trial-code idea. - **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 (`pnpm stripe:listen`) which forwards real signed events; a real checkout carries the `famId` and drives the DB write end-to-end. ### 5.3.2 Access gating (`fams.paymentMode` / `accesscodes`) ``` computeFamAccess(fam, code?) → { disabled, reason } lib/server/access.ts none → disabled ("no_access") fresh signup, no code/sub code → valid while accesscodes.active && !expired && !durationExhausted (duration/expiry 0 = continuous/never; months measured from fam.accessCodeEnteredAt / code.createdAt) sub → follows webhook-maintained fams.active canceled → disabled ("canceled") ensureFamAccess(famId): reads fam+code, persists drifted fams.active, returns {fam, access} applyAccessCode(famId, value): validates + sets paymentMode='code' + entry stamp ``` - Exposed to all fam pages as `data.famAccess` from `[fam]/+layout.server.ts`. - Disabled UX: layout blurs page content behind an overlay card + admin TopNav announcement (`/settings` is exempt so admins can apply a code / manage billing); member kanban renders empty locked columns and `toggle()` early-returns (frontend-only by decision). - Entry points: optional code field at signup, Access card in settings (`?/applyCode`). Webhooks flip `paymentMode` to `sub`/`canceled`. - Debug revoke: with the platform `debug` flag ON, settings shows a "Revoke code" CTA (`?/revokeCode`) that clears the applied code (back to `none`/gated). Server-side flag check is the boundary. - Seeded dev code: `dev123` (developer, duration 0, expiry 0). ### 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 pocketbase.ts (pbAdmin), migrate.ts, access.ts, platform.ts, services/ /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 /pricing, /signup wizard, /api/webhooks/stripe) /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. - **Server data access:** `servicesFor(event)` / `createServices(pb)` in `$lib/server/services/`; superuser ops via `pbAdmin` facade. - **Browser data access:** same-origin fetch to `/api/*` SvelteKit endpoints; httpOnly `pb_token` cookie is the auth. - **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** — implemented in SvelteKit (`/pricing` public picker + inline signup checkout, settings Billing group with billing portal, `/api/webhooks/stripe` → `stripe-events.ts`; `?checkout=return` lands on the fam dashboard with a welcome notice). Remaining: platform-admin UI for managing `accesscodes`, prod webhook secret wiring, optional Stripe-level pause (see TODO.md). - **Weekly CRON** (`/api/weekly-cron`, Coolify) — not implemented; settlement is manual via `complete-week`/`simulateEow`.