Project Configuration

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

FamChore v2 — AI Agent Reference

Stack

SvelteKit (SSR frontend) + Hono proxy (same container, port :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 → PB SDK directly (auth via device token or admin JWT)
Admin CRUD: Browser → PB SDK (admin JWT)
Reward creation: After completion toggle, SvelteKit server creates reward if threshold met
Weekly CRON: Coolify → GET /api/weekly-cron on Hono → Hono queries PB, computes summaries, upserts weekly_history
Strip donate: Browser → Hono /api/stripe/create-checkout → Stripe → Hono webhook → update fam
WhatsApp: Deferred — Hono CRON handler has pluggable notification interface

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
Environment: PB_URL, PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD, STRIPE_SECRET_KEY, DONATION_MODAL_INTERVAL
Seed via JSON dump (portable for dev)
Monorepo: SvelteKit in /src, Hono in /proxy, two Dockerfiles

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 Deploy PocketBase on Coolify → validate data persists 1.4 Deploy SvelteKit+Hono on Coolify → validate routing 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 PB realtime SSE subscriptions from FE 2.7 Remote functions (PB SDK client helpers)

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.1 KiB Raw Blame History