Architecture

Valcraven is a Next.js 16 app deployed to Cloudflare Workers (via OpenNext), backed by D1 (SQLite) through Drizzle ORM, R2 for object storage, and Cloudflare Queues for background work — with a separate realtime Worker hosting the AI agent. It ships as an npm-workspace monorepo so the web app, the agent Worker, the Expo mobile app, and a shared types package all live in one repo.

This section is the mental model. Read it once and the rest of the docs — features, building recipes, deployment — will make sense faster. Each page focuses on one layer:

• Monorepo layout — the npm workspaces (apps/web, apps/realtime, apps/mobile, packages/core), what each one is, and the rule that decides where new code goes.
• Request & auth lifecycle — how a request travels from the edge cache through middleware, the OpenNext worker, and into an API route, and where the session is checked at each step.
• Cloudflare Workers & OpenNext — how a Next.js app runs on Workers: the custom worker.js entrypoint, the wrangler bindings (D1, R2, Queues, the realtime service binding), the scheduled/queue handlers, and the nodejs_compat story.
• The realtime Worker — what apps/realtime is, why the AI agent runs as a Durable Object in a separate Worker, and how the web app talks to it.
• Data layer (D1 + Drizzle) — getDb() vs getRawDb() vs getRawAdapter(), the schema, migrations, and the multi-dialect (SQLite / Postgres / D1) design.

Extending the template rather than understanding it? Jump to Building with Valcraven. Deploying it? See Deployment & Operations.