System Architecture
Doc Status: Good | ✓ Clear summary | ✓ Easy to read | ✓ Matches code | ✓ Good structure | ✓ Professional look | ✓ Visual components
Architecture Diagram
Data Flow
App Data — Convex
All app data (students, courses, attendance, payments) flows through Convex:
Browser / Mobile
│
│ useQuery / useMutation (real-time, auto-subscribed)
▼
Convex DB
(queries / mutations — atomic, transactional)
External APIs — Convex Action
Lark, Meta CAPI, ZNS are called from a Convex action using the vendor’s own SDK or fetch:
Convex Action
│
│ fetch / vendor SDK
▼
External API (Lark / Meta CAPI / ZNS)
Inbound Webhooks — CF Worker → Convex
Cloudflare Workers are HTTP entry points only — they verify the signature and forward to a Convex httpAction:
External Service (Lark / Meta)
│
│ POST webhook
▼
CF Worker (Hono) — verify signature only
│
│ httpAction call
▼
Convex (business logic)
Deployment Targets
| Surface | Where | How |
|---|
| App data backend | Convex Cloud | npx convex deploy --prod |
apps/website | Cloudflare Workers Static Assets | pnpm build && wrangler deploy |
apps/admin | Cloudflare Workers Static Assets | pnpm build && wrangler deploy |
apps/lark-sync | Cloudflare Workers (Hono) | wrangler deploy |
apps/meta-conversions-worker | Cloudflare Workers (Hono) | wrangler deploy |
| Marketing CMS (Sanity) | Sanity Cloud | Managed by PM via Studio |
apps/mobile | EAS Build → App Store / Play Store | eas build |
Auth
Convex Auth (@convex-dev/auth) is the auth library. It owns the users / authAccounts / authSessions / authVerificationCodes / authVerifiers tables and exposes sign-in / sign-out hooks.
| App | Client Provider |
|---|
| Admin | ConvexAuthNextjsProvider |
| Mobile | ConvexAuthProvider + expo-secure-store |
| Website | Public (no auth) |
apps/lark-sync, apps/meta-conversions-worker) authenticate via shared secret, not Convex Auth.
Key Environments
| Environment | Branch | URL |
|---|
| Production | main | wondersound.vn, admin.wondersound.vn |
| Staging | dev | dev.wondersound.vn |
| Convex dev | local | npx convex dev |
CI/CD
| Trigger | Action |
|---|
Push to main | Deploy website to CF (prod), Convex prod |
Push to dev | Deploy website to CF (staging) |
| Sanity publish | GitHub dispatch → rebuild website |
