# Architecture

One Worker owns web rendering, API requests and scheduled execution.

The production web app is a TanStack Start application built with the Cloudflare Vite plugin. Its Worker handles SSR, Better Auth, oRPC, the files gateway, MCP, AI streaming, OG images and cron. Expo calls the same HTTP API. There is no separate API deployment.

<Diagram name="architecture" alt="Web and mobile call one Worker; the Worker uses Hyperdrive and Postgres for records, R2 for files, and outbound providers for delivery." />

## Runtime and infrastructure [#runtime-and-infrastructure]

| Component | Responsibility |
| --- | --- |
| TanStack Start | Routes, SSR, hydration and request handlers |
| Worker fetch | Carries Cloudflare waitUntil into the request runtime before dispatch |
| Hyperdrive | Pools connections to Postgres; query caching must stay disabled |
| Postgres, hosted on Neon | Users, Organizations, domain records, leases, outboxes and approvals |
| R2 | Private objects, accessed through the files-sdk fetch adapter |
| Worker scheduled | Runs the six jobs in one scoped Effect program |

The default build targets Cloudflare. `DEPLOY_TARGET=node` selects Nitro for a Node deployment. `vite dev` always uses Nitro, with a shim for `cloudflare:workers` and direct `DATABASE_URL` access. The Node path is useful locally; the built Worker remains the compatibility test for production.

## Read the implementation [#read-the-implementation]

- [Request lifecycle](/docs/architecture/request-lifecycle) follows one authenticated request.
- [Client/server boundary](/docs/architecture/client-server-boundary) explains which imports are safe.
- [Effect at the edges](/docs/architecture/effect) covers deadlines, cancellation and retries.
- [Observability](/docs/architecture/observability) distinguishes application logs from Worker traces.

Shared code belongs in a package when web and mobile need the same contract or behavior. The [package reference](/docs/packages) lists actual exports. Adding a feature usually extends the existing Worker, schema and router, rather than provisioning another service.


## Key files [#key-files]

- [`apps/web/src/server.ts`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/src/server.ts)
- [`apps/web/vite.config.ts`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/vite.config.ts)
- [`apps/web/wrangler.jsonc`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/wrangler.jsonc)
- [`packages/db/src/connection.ts`](https://github.com/CarlosZiegler/doro/blob/main/packages/db/src/connection.ts)