JCEEE
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
## 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)
|