init repo

2026-06-23 11:27:05 +01:00
commit 2253b54077
37 changed files with 2382 additions and 0 deletions
@@ -0,0 +1,106 @@
+## 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)