Architecture

Monorepo Layout

.
├── apps/
│   ├── web/                 # Frontend (SvelteKit + Vite → Cloudflare Pages)
│   ├── api/                 # Backend API (oRPC → Cloudflare Worker)
│   └── docs/                # Documentation site (VitePress → Cloudflare Pages)
├── packages/
│   ├── db/                  # Drizzle ORM + D1 schema + migrations
│   ├── auth/                # better-auth configuration + helpers
│   ├── email/               # Resend email sender
│   ├── storage/             # R2 client for photo evidence & payment proofs
│   └── shared/              # Shared types, utilities, constants
├── pnpm-workspace.yaml      # Workspace definitions + dependency catalogs
├── package.json
├── turbo.json               # Build orchestration
├── biome.json               # Formatter + linter config
└── lefthook.yml             # Pre-commit hooks

Namespaces

Directory	Package Namespace	Example
apps/*	@apps/*	@apps/web, @apps/api
packages/*	@packages/*	@packages/db, @packages/auth

Data Flow

User → Cloudflare Pages (apps/web)
            ↓
      oRPC API (apps/api)
            ↓
      D1 Database (packages/db)
            ↓
      Auth (packages/auth) → better-auth + Google OAuth + Email/Password + Magic Link + Bearer + JWT
      Email (packages/email) → Resend
      Storage (packages/storage) → Cloudflare R2

Package Boundaries

• @packages/db exports schema, migrations, and a createDb(env) factory.
• @packages/auth exports auth instance and getSession helpers.
• @packages/email exports createEmailClient, sendMagicLinkEmail, and sendNotificationEmail.
• @packages/storage exports R2 client and upload helpers with validation.
• @packages/shared exports TypeScript types and utilities used by both frontend and backend.

API Architecture (oRPC)

Middleware (apps/api/src/middleware/) →  Auth chain, role checks, context builders
Routes (apps/api/src/routes/)        →  Route handlers (guard + governance + service call)
Services (apps/api/src/services/)    →  Pure business logic, no auth awareness

The API entrypoint is a pure Cloudflare Workers fetch handler. No additional HTTP framework is used — oRPC's OpenAPIHandler from @orpc/openapi/fetch handles request routing directly.

Deployment Model

• apps/web deploys to Cloudflare Pages.
• apps/api deploys to Cloudflare Workers.
• apps/docs deploys to Cloudflare Pages (separate site from apps/web).
• apps/web and apps/api share the same D1 database binding per environment.
• apps/docs is a static site with no backend dependency.

Workers vs Pages

App	Platform	Wrangler Config
apps/api	Workers	Supports env.development and env.production keys
apps/web	Pages	No env keys — env vars dashboard-managed or via --branch CLI
apps/docs	Pages	No env keys — static site

Documentation Architecture

• Human docs: apps/docs (VitePress) — overview, tech stack, architecture, user flows.
• API docs: Auto-generated OpenAPI spec served by apps/api at /api/openapi.json with Scalar UI at /api/docs.
• AI rules: .agents/ knowledge system — hard rules and conventions for code generation.
• No duplication: API endpoint docs live only in OpenAPI. Human docs link to it.
• Hot deploy: apps/docs deploys on every push to main. Keep it in sync with codebase changes.

README.md

The root README.md is minimal. It contains:

• One-line project description
• Link to apps/docs/index.md for full documentation
• Link to /api/docs for API reference
• Quick setup instructions (pnpm install, dev commands)

Do NOT duplicate apps/docs content in README.md.

apps/docs/

The documentation site is built with VitePress and deployed to Cloudflare Pages. It is divided into two sections:

• overview/ — Non-technical docs: project goals, product features, getting started.
• technical/ — Technical docs: architecture, tech stack, auth, database, deployment, user flows.

API endpoint documentation is NOT in VitePress. It is auto-generated from the oRPC contract and served by apps/api at /api/openapi.json with Scalar UI at /api/docs. The docs site only links to it.

For docs conventions and update rules, see .agents/rules/docs.md.