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 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.