Foundation layers for a complete Cloudflare application

Put static assets, request logic, structured data, object storage, and background work at the right boundaries.

ARCHITECTUREINTERMEDIATE30 minutesOutcome: an application responsibility map

A complete application does not connect every Cloudflare product. It completes one user flow from a page through server-side validation and business logic into correct data operations, with failure, observability, and rollback defined. Choose products from responsibilities, not from the catalog.

Five responsibility layers

Layer	Responsibility	Common choice	Must not own
Static delivery	HTML, CSS, JS, immutable assets	Workers Static Assets	User authorization or secrets
Request logic	Routing, authentication, validation, response composition	Worker	Long blocking jobs
Structured state	Users, tenants, articles, job status	D1	Large original files
Object data	Images, PDFs, exports	R2	Frequent relational queries
Background work	Conversion, indexing, retry, batch work	Queues or Workflows	Holding the user request open until everything finishes

KV is not the default database

KV fits read-heavy configuration and cache-like data that tolerates eventual consistency. Evaluate D1 for relational queries, transaction semantics, or strict tenant predicates. Evaluate Durable Objects when the problem is stateful coordination.

Synchronous request boundary

Synchronous request path for a complete application — Keep the synchronous request on a clear path. D1, R2, and Queue are downstream resources that the Worker accesses only when required.Open original

01
Entry
A static page or API request.
02
Resolve
DNS and proxying determine the entry path.
03
Protect
TLS, WAF, and cache decisions precede application code.
04
Execute
The Worker verifies identity, input, and tenant.
05
Access resources
Read only the data needed by this flow.

A maintainable request

Classify the route first

Deliver static assets directly. Allow caching for public reads. Authenticate protected APIs and apply an additional role check to administrative actions. Avoid one universal handler that guesses every behavior.

Establish business context

Authentication produces userId and tenantId. Every D1 query binds a tenant predicate, and each R2 key uses a controlled prefix. A tenant ID submitted by the browser is never authorization by itself.

Move long work out of the request

Image batches, PDF parsing, indexing, and external API retries first create a job record, then send a Queue message or start a Workflow. Return a job ID and expose progress through a status endpoint.

Define responses and observation

Success, invalid input, unauthorized access, missing resources, and downstream failure receive stable error codes. Logs include request ID, version, and an internal error category, but not secrets, complete tokens, or unnecessary personal data.

How four projects differ

SaaS

D1 stores accounts, tenants, and plans. Add R2 only for attachments. Customer code execution is a separate advanced problem.

CMS

D1 stores content state and index fields. R2 stores media. Publishing creates an explicit public version.

Image utility

R2 stores originals or results. Images handles supported transforms. Queue absorbs non-interactive batch work.

PDF utility

Browser Run can generate PDFs from HTML or a URL. Parsing and indexing uploaded files belong in an asynchronous flow.

Completion checkpoint

Write a five-line responsibility map for your project. Each resource should have one primary job and a defined user-visible failure. If the design keeps one request open for conversion, indexing, and notification, extract a background job before continuing.

For Next.js, complete the target-runtime compatibility gate. Use the D1 migration and recovery guide for database release. Next: choose a complete project.

Learn framework and platform responsibilities separately

For an application using TanStack Start, Router, or Query, use the TanStack ecosystem map to assign routing, SSR, Server Functions, and server-state responsibilities. Then return here to map static delivery, request logic, data, and background work onto Cloudflare. The related technology guide network covers the other runtime and data topics.