Project Configuration

Language: TypeScript
Package Manager: pnpm
Add-ons: prettier, tailwindcss, sveltekit-adapter, experimental

FamChore v2 — AI Agent Reference

Stack

SvelteKit (SSR frontend, internal :2080) + Hono proxy (internal :3456) + nginx (container :3001)
PocketBase (separate Coolify service at pb.chores.app.com, :8090)
Stripe one-time donations
Coolify CRON → GET /api/weekly-cron
Deployment: Coolify, Cloudflare DNS

Auth

Role	Auth	Session
Super admin (me)	PB email+pass	24hr JWT
Fam admin	PB email+pass	24hr JWT, scoped to own fam
Member	Invite code + device token	localStorage, no expiry

PB Collections (all scoped by `famId`)

fams — name, slug, inviteCode, stripeCustomerId, featureFlags
members — famId, name, color, deviceToken(hashed), deviceTokenHint
chore_templates — famId, name, defaultValue, defaultFrequency
assigned_chores — famId, memberId, templateId, frequency, value
completions — famId, memberId, assignedChoreId, date
weekly_history — famId, memberId, weekStart, pointsEarned, moneyEarned
rewards — famId, memberId, source, label, value, claimed, claimedAt
monthly_bonuses — famId, month, prizeType, prizeValue, winnerMemberId
settings — famId, pointsThreshold, weeklyBonus, webhookUrl

Routes

/                    Landing (SaaS marketing)
/admin               Admin panel - statistic dashboard, and any donations made
/join/:code          Member invite code
/{fam}               Fam dashboard
/{fam}/admin         Admin panel
/{fam}/:username     Member kanban (?token= for auth)
/api/*               Hono proxy (webhooks, CRON)

Data Flow

Chore toggle: Browser → Hono proxy → PB (auth via device token or admin JWT)
Admin CRUD: Browser → Hono proxy → PB (admin JWT)
Reward creation: After completion toggle, Hono proxy creates reward if threshold met
Weekly CRON: Coolify → GET /api/weekly-cron on Hono → Hono queries PB, computes summaries, upserts weekly_history
Stripe donate: Browser → Hono /api/stripe/create-checkout → Stripe → Hono webhook → update fam
WhatsApp: Deferred — Hono CRON handler has pluggable notification interface
UI reactivity: Svelte $state / $derived / $effect — no PB SDK .subscribe() / SSE

Conventions

Every collection query includes famId = @request.auth.famId filter
Super admin bypasses famId filter (access via PB admin API)
deviceToken stored as SHA-256 hash; never log raw tokens
config.ts at root for dev/build-time shared config (e.g. PROXY_PORT); runtime config via env vars
.env at root tracks port values (PROXY_PORT, PORT); .env.example committed as template
Docker: docker/Dockerfile (prod, multi-stage + nginx) + docker/Dockerfile.dev (PocketBase)
Nginx routes in prod: /api/* → Hono (:3456), /* → SvelteKit (:2080)
Ports: frontend 2080, proxy 3456, container ext 3001 (port 3000 is reserved)
Environment: FRONTEND_PORT, PROXY_PORT, PB_PORT, PB_EMAIL, PB_PASSWORD, DEBUG_RECORD_ID, STRIPE_SECRET_KEY, DONATION_MODAL_INTERVAL
Seed via JSON dump (portable for dev)
Monorepo: SvelteKit in frontend/, Hono in proxy/, two Dockerfiles
Decisions tracked in MEMORY.md

Build Phases (must validate each before next)

Phase 1 — Infrastructure

~~1.1 Scaffold SvelteKit + Hono monorepo~~ ~~1.2 Write Dockerfiles (frontend + backend, correct port mapping)~~ ~~1.3 Sort out vars (.env + .env.example)~~ ~~1.5 Validate Hono /api/* reachable, env vars injected~~ ~~1.6 Validate SvelteKit↔PB connectivity (admin API read/write)~~

Phase 2 — Backend Core

2.1 Create PB collections via schema/migration 2.2 Super admin seed + fam signup flow 2.3 Fam admin login (email/pass → 24hr JWT) 2.4 Invite code generation + member join flow 2.5 Device token auth + route guards 2.6 Svelte reactive state management (no PB SSE)

Phase 3 — Backend Data Streams

3.1 Chore template CRUD + assignment grid (admin) 3.2 Completion toggle (member → PB direct) 3.3 Weekly progress + history computation 3.4 Reward auto-creation on threshold 3.5 Reward claim flow + admin CRUD 3.6 Monthly bonus evaluation 3.7 CRON handler (Coolify → Hono) 3.8 Stripe checkout + webhook 3.9 Notification interface (WhatsApp deferred)

Phase 4 — Frontend App

4.1 Member kanban (3-column, live SSE updates) 4.2 Admin dashboard (weekly overview, chart) 4.3 Admin panel (members, chores, rewards, settings) 4.4 Landing page (SaaS marketing) 4.5 Super admin stats dashboard 4.6 Donation modal 4.7 QR invite code 4.8 Polish (loading, empty, error states, responsive)

4.9 KiB Raw Blame History