Backend Architecture — Clean Backends on Cloudflare Workers

Projects preserve clean dependency direction, explicit boundaries, testability, and one composition root, but may use DDD or hexagonal architecture. Detect and follow the existing architecture; do not force DDD terminology onto ports-and-adapters code. Sections marked [detect: …] name evidence to read before editing. Select reference code by its contract and responsibility, not repository age. Existing RPC envelopes are compatibility cases, not the default for a bare-value server function.

When Effect is present, treat Context.Tag services as ports, Layers as adapter constructors and dependency composition, and Effects as typed programs. Keep pure domain logic pure, provide Layers at the composition root, and run Effects only at entrypoint/runtime boundaries. Do not create hidden global runtimes or duplicate error logging.

Backends live inside the TanStack Start app: apps/<app>/src/server/. No separate worker app.

Layering

• Domain — entities, value objects, pure business logic. Zero dependencies on other layers, framework-agnostic.
• Application — use cases and handlers. Orchestrates domain models and outbound ports. Depends on Domain and application-owned port contracts.
• Infrastructure — DB, external APIs, queues, storage, and subprocess adapters. Implements outbound ports without owning use-case sequences.
• Entrypoints — receive external input or control across the system boundary and translate it into application calls.