Use Cases

Semitra fits product teams that want a conventional full-stack app shape on Cloudflare Workers without assembling routing, persistence, authorization, serialization, background work, storage, realtime, cache, tenancy, and frontend contracts from scratch.

It is best for JSON-first applications where the backend owns the authoritative rules and the generated frontend consumes typed contracts.

When Semitra is a good fit

Choose Semitra when the app needs most of these traits:

• a Cloudflare Worker backend with D1, R2, KV, Queues, or Durable Objects
• REST-like JSON endpoints under a stable versioned API such as /api/v1
• runtime validation for request, model, job, mail, and channel payloads
• explicit controller, policy, record, and resource boundaries
• a generated React Router 7, Vite, and Tailwind frontend path
• background jobs, events, mail, uploads, cache, realtime, or tenancy
• conventions that AI agents and human developers can follow consistently

Semitra is less ideal when you need backend-rendered HTML templates, a non-Cloudflare deployment target, a completely open frontend stack, or a Node-only request runtime.

Use-case map

Use case	Semitra pieces	Why it fits
Multi-tenant SaaS workspace	Tenancy, policies, D1 records, resources, cache, storage	Tenant resolution stays centralized while each request uses tenant-aware persistence, cache, and object keys.
Internal operations dashboard	React Router frontend, typed API client, controllers, records, policies	Teams get a predictable API and UI contract without hand-wiring framework boundaries for every screen.
Customer portal with uploads	Records, resources, policies, R2 storage, attachments, mailers	Records own metadata, storage owns binary bodies, and policies decide who can see or mutate files.
Content or workflow app	Routes, controllers, records, events, jobs, mail	State changes can emit domain events, enqueue durable jobs, and notify users outside the request path.
Realtime notification center	Channels, Durable Object coordination, events, policies	Clients subscribe to rooms while the backend keeps authorization and broadcast semantics explicit.
Data ingestion pipeline	Mailboxes, jobs, queues, records, storage	Inbound payloads can be validated, stored, processed asynchronously, and exposed through JSON resources.
Public JSON API plus web app	Versioned routes, resources, frontend models, API client	Backend response contracts and frontend parsing stay aligned through schema-backed models.

Scenario: multi-tenant project tracker

A project tracker has teams, projects, tasks, comments, uploaded attachments, and notifications. Semitra gives this app a direct full-stack shape:

1. Resolve the tenant from a subdomain or x-semitra-tenant header.
2. Define Project, Task, and Comment records with schema-backed attributes and D1 migrations.
3. Put authorization in policies such as TaskPolicy and ProjectPolicy.
4. Serialize client responses with resources such as TaskResource.
5. Store task attachments in R2 through record attachments.
6. Emit an event when a task is completed.
7. Enqueue jobs for email notifications or external sync.
8. Broadcast realtime status updates through a channel.
9. Consume /api/v1 from the generated React Router frontend through typed API endpoints and frontend models.

The framework boundaries stay the same as the app grows:

Request -> Router -> Controller -> Policy -> Model -> Events -> Resource -> Response

Scenario: customer support portal

A support portal receives inbound email, creates tickets, lets customers upload files, and notifies support staff.

Use Semitra like this:

• SupportMailbox validates inbound mail and emits a tickets:received event.
• CreateTicketJob performs durable ticket creation or external sync.
• Ticket and Message records persist normalized state in D1.
• TicketPolicy scopes customer and agent access.
• TicketResource exposes the public JSON shape.
• SemitraStorage stores attachments in R2 with tenant-aware keys.
• NotificationsChannel broadcasts ticket updates to connected agents.
• The generated frontend defines typed endpoints for list, detail, reply, and attachment flows.

This is a good Semitra use case because the app uses most framework layers, but each layer has a single job.

Scenario: admin analytics and exports

An internal admin app needs dashboards, export generation, and short-lived derived metrics.

Use Semitra like this:

• Controllers expose JSON endpoints for dashboard widgets.
• Records query D1 through structured filters and ordering.
• Cache stores derived metrics for short periods.
• Jobs generate CSV or PDF exports after the request returns.
• Storage writes generated files to R2.
• Mailers notify users when exports are ready.
• Policies keep admin-only metrics out of ordinary user scopes.

Cache accelerates reads, jobs handle durable work, storage owns the export body, and resources define the client payloads.

How to choose a subsystem

Use this rule of thumb:

Need	Use
Match a URL to an action	Routing
Coordinate request work	Controller
Authorize an action or scope records	Policy
Persist relational application state	Record
Define response shape	Resource
Publish that something happened	Events
Run durable work later	Jobs
Compose or receive email	Mailers and mailboxes
Store object bodies or attachments	Storage
Cache disposable derived data	Cache
Coordinate live connections	Realtime channels
Resolve customer or workspace context	Tenancy

Read next

• Full-Stack Apps
• Request Lifecycle
• Conventions and Layout
• AI Agent Reference