Cloudflare Composition Root

Cloudflare Composition Root

Use a composition root: each runtime entrypoint turns raw Cloudflare capabilities into application-owned dependencies, assembles services, and invokes them. Inner code receives ports, never Env, raw bindings, framework service locators, or binding names.

Cloudflare entrypoint
  → tracer + parsed configuration
  → binding adapters
  → exact service dependencies
  → application service
  → protocol projection

Apply ../coding-standards/SKILL.md for TypeScript contracts, parsing, errors, side effects, and tests. When implementation shape is unclear, consult EXAMPLES.md for Hono, WorkerEntrypoint, adapter, and refactor templates.

Ownership

• Entrypoint adapter: parses the external request/event, establishes invocation context, constructs dependencies, invokes a service, and projects its result.
• Binding adapter: implements an application-owned port using KV, R2, D1, Durable Objects, Queues, service bindings, Workflows, or another external capability.
• Application service: owns one use case's sequencing, fallback, retry, and best-effort policy.
• Domain module: owns pure values and invariants.
• Port: names exactly the capability a consumer needs; it does not mirror a Cloudflare API.

Raw platform values may exist only in composition roots and binding adapters. A binding adapter accepts the smallest platform capability, not all of Env.

1. Map the boundary

Inspect repository instructions and the affected:

• Hono app factories, middleware order, route registration, and context types;
• Worker, WorkerEntrypoint, Durable Object, Workflow, queue, and scheduled entrypoints;
• Env declarations and every use of the relevant binding;
• tracer creation, correlation, error reporting, and detached-work ownership;
• existing services, adapters, ports, tests, and architecture checks.

Trace each affected behavior from entrypoint to side effect and caller-visible result. For refactors, record current error, retry, fallback, serialization, and tracing behavior before moving it.

Completion criterion: Every affected entrypoint, binding consumer, behavior, lifecycle, side effect, failure policy, and existing test seam is accounted for.

2. Design application-owned dependencies

Define contracts from consumer needs:

/** Persistence capability required by document application services. */
export interface DocumentStore {
  /** Find one document by its domain ID. */
  find(id: DocumentId): Promise<Document | null>;
  /** Persist one valid document. */
  save(document: Document): Promise<void>;
}

/** Exact dependencies of the publish-document use case. */
export type PublishDocumentDependencies = Readonly<{
  documents: DocumentStore;
  clock: Clock;
  tracer: Tracer;
}>;

Rules:

• Use domain inputs and parsed outputs, not raw keys, strings, request objects, or binding options.
• Expose only operations required by real callers.
• Keep each service's dependency object exact; never create a shared mega-bag or rename Env to Dependencies.
• Put platform serialization, keyspaces, pagination tokens, TTLs, metadata, and output parsing in the binding adapter.
• Let the application service own policy. The adapter translates failures precisely enough for the service to distinguish recoverable conditions from corruption and defects.
• Inject Tracer into services and adapters that create spans; do not add it to every method signature.
• Add an application-owned factory only when scope is genuinely dynamic after composition, such as account-bound construction after authentication. The factory must not expose Env or raw bindings.

Choose lifetimes explicitly:

• Reuse immutable adapters and services when their bindings and tracer are safe across concurrent invocations.
• Construct per invocation when they retain request-scoped runtime objects or mutable invocation state.
• Hand detached work to an explicit owner such as a narrow background-task port; do not leak ExecutionContext inward.

Completion criterion: Every inner signature uses application/domain types; each operation and factory has a current caller; and dependency, tracer, and side-effect lifetimes have explicit owners.

3. Build or refactor

New service branch

1. Implement the application service against its ports without importing Hono or Cloudflare runtime types.
2. Implement one binding adapter per external role. Give technology-specific implementations explicit names, such as WorkersKvDocumentStore.
3. Keep protocol concerns in the HTTP, RPC, queue, Workflow, or scheduled adapter.
4. Compose the service at every entrypoint that serves the use case.