ENGINEERING CASE STUDY · DWG FG-002 · 2026 / ONGOING
420finder Platform
Multi-Tenant SaaS Architecture · Access Control · Serverless on AWS
Designing a multi-tenant operations platform for private social clubs with strict tenant isolation, role-based staff permissions, prepaid member wallets, and in-person order workflows.
| Project | 420finder | Doc ID | FG-002 |
|---|---|---|---|
| Role | Founder & Software Architect (Finder Group) | ||
| Stack | TypeScript · React · AWS · Terraform | Sheet | 3 / 5 |
| Infra | API Gateway · Lambda (Node 22) · DynamoDB · Cognito · S3 · KMS | ||
| Links | |||
01 / Domain Scope & Multi-Tenancy System boundaries
Private social clubs manage physical check-ins, member registries, catalog inventory, and prepaid member balances, often relying on disconnected spreadsheets or legacy point-of-sale tools.
420finder provides a unified, multi-tenant web and API platform where each club operates in an isolated partition while platform operators oversee onboarding, staff provisioning, and club activation from a central console.
Core Capabilities
- Three-Tier Role Model: Cognito groups and claims separate
super-admin(platform governance), clubmanager(catalog, inventory, and member top-ups), andcashier(read-only catalog and in-person order checkout). - Prepaid Wallet & Orders: Member top-ups and in-person order deductions tied to club-scoped DynamoDB items and GSI1 access patterns.
- Direct Media Uploads: Product photos upload directly from the browser to S3 via presigned URLs so Lambda handlers never buffer binary payloads.
02 / Architectural Decisions & Trade-offs Design records
| Area | Context | Decision | Outcome & Trade-off |
|---|---|---|---|
| Tenant Gate | UI route hiding alone is insufficient if a deactivated club still has staff with unexpired JWT sessions. | Enforce club activation and tenant ownership server-side via requireClubAccess across all product, member, and order handlers. |
Deactivating a club from /superadmin revokes API access across all endpoints immediately, regardless of active browser tokens. |
| Terraform Split | A single monolithic Terraform state slows down plan/apply cycles and increases blast radius as handlers grow (~100 package scripts). | Split infrastructure into independent states: terraform/web/, terraform/api/core/ (API Gateway, Cognito, DynamoDB, KMS), and domain stacks under terraform/api/areas/<area>/. |
Requires explicit -backend-config per area, but keeps deployments fast, isolated, and scoped to the domain being modified. |
| Runtime Parity | Local tooling (pnpm, Vite, Vitest) benefits from Node 24, while AWS Lambda runtime targets nodejs22.x without ESM zip overhead. |
Pin @types/node in apps/api to major 22 and bundle each handler via esbuild to CommonJS (--target=node22) grouped by area. |
TypeScript catches any Node 24-only API usage at compile time before code ever reaches Lambda, while keeping zero-config CJS cold starts. |
03 / Quality Gates & CI/CD Delivery Verification
Verification & Seed Tooling
- Pre-merge Quality Gate (
pnpm qa): Runs ESLint, workspace-wide TypeScript checks, Vitest unit and integration suites, and esbuild handler bundling beforeterraform validate. - Dry-Run Seed Harnesses: Idempotent CLI scripts (
seed:dev-club,seed:demo-members,seed:orders) support--dry-runpayload inspection before writing to live dev environments.
Environment Promotion & Runbooks
- OIDC & Protected Production: GitHub Actions authenticates to AWS via keyless OIDC;
mainauto-deploys todevafter CI passes, whileprodrequires manualworkflow_dispatchand environment reviewer approval. - Operational Readiness: Repository includes operational runbooks (
docs/runbooks/) for alarm triage, failed deployments, and data recovery.
Drawing Set Navigation Sheets 1 to 5
Continue to the Zelo App case study or return to the executive overview.