## 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 → 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
- `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_URL`, `PB_ADMIN_EMAIL`, `PB_ADMIN_PASSWORD`, `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 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)