AI Agent Reference

This page is written for both humans and retrieval tools. It summarizes the stable Semitra facts an AI agent should use before generating or editing a Semitra project.

The public docs remain the source to retrieve from. This page is an index of the facts that should be treated as canonical.

Framework identity

Semitra is a Rails-inspired application framework for Cloudflare Workers. It is not a Rails clone.

The product shape is:

• Cloudflare-native Worker backend
• JSON-first APIs
• TypeScript schema contracts across layers
• D1 records, R2 storage, KV cache, Queues jobs, Durable Object realtime
• generated React Router 7, Vite, and Tailwind frontend
• typed frontend helpers through @semitra/cli/frontend

Request flow

Always preserve this flow:

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

Use each layer for one responsibility:

Layer	Responsibility
Router	Map method and path to controller action.
Controller	Coordinate params, authorization, records, side effects, and rendering.
Policy	Authorize actions, scope records, and expose field visibility.
Model	Persist D1-backed application state through SemitraRecord.
Events	Publish domain signals and fan-out reactions.
Jobs	Run durable queued work.
Resource	Define public JSON response shape.
Response	Return a Web Standard Response.

Canonical app layout

Backend Semitra apps use this source layout:

app/
  controllers/
  models/
  resources/
  policies/
  jobs/
  mailers/
  mailboxes/
  channels/
config/
  application.ts
  routes.ts
db/
  migrate/
  schema.ts
src/
  index.ts

Generated full-stack workspaces use:

apps/api
apps/web

apps/api owns the Worker backend. apps/web owns the React Router frontend.

Base classes

Use Semitra-prefixed framework base classes through app-level base classes:

Framework class	App-level class
SemitraController	ApplicationController
SemitraRecord	ApplicationRecord
SemitraResource	ApplicationResource
SemitraPolicy	ApplicationPolicy
SemitraJob	ApplicationJob
SemitraMailer	ApplicationMailer
SemitraMailbox	ApplicationMailbox
SemitraChannel	ApplicationChannel

Cloudflare mapping

Cloudflare primitive	Semitra subsystem
D1	Records and migrations
R2	Storage and attachments
KV	Cache
Queues	Jobs and queued events
Durable Objects	Realtime coordination

Application code should use Semitra abstractions before raw Worker bindings.

Common task recipes

Add a JSON resource endpoint

1. Add or update a migration under db/migrate.
2. Add a SemitraRecord model under app/models.
3. Add a SemitraResource serializer under app/resources.
4. Add a SemitraPolicy under app/policies.
5. Add a controller action under app/controllers.
6. Add a route in config/routes.ts, usually under api(() => { ... }).
7. Run semitra codegen.
8. Add or update tests for the request contract and behavior.

Add frontend access to an endpoint

1. Add a frontend model under apps/web/app/models.
2. Add a defineSemitraEndpoint(...) entry in apps/web/app/lib/api.ts.
3. Parse responses with the frontend model schema.
4. Keep API calls centralized in app/lib/api.ts or small hooks that wrap it.
5. Use VITE_API_BASE_URL only when the API runs on a different origin.

Add durable side effects

1. Emit a domain event when the application state changes.
2. Use a job when work must be durable, retryable, or delayed.
3. Define payload schemas for event or job payloads.
4. Preserve trace IDs and tenant context when using envelopes.

Add tenant-aware uploads

1. Resolve the tenant in config/application.ts.
2. Store relational metadata in D1 records.
3. Store object bodies in R2 through SemitraStorage or record attachments.
4. Use policies to decide who can upload, replace, read, or delete files.
5. Use tenant-aware key prefixes instead of manually concatenating tenant keys in controllers.

Do not infer these incorrectly

• The example header-based currentUser pattern is demonstration auth, not a production session system.
• The root repo currently has no canonical root lint or typecheck script.
• apps/docs/dist and .semitra/generated are generated outputs, not the source docs or source app code.
• nodejs_compat in a Worker config does not make Node APIs part of the Semitra runtime contract.
• Backend response shape belongs in resources, not ad hoc controller objects when returning records.
• Frontend architecture is chosen: React Router 7 framework mode, Vite, and Tailwind CSS.

Retrieval targets

Use these pages for focused context:

Question	Page
What should I build with Semitra?	Use Cases
How do apps/api and apps/web fit together?	Full-Stack Apps
How does a request move through the framework?	Request Lifecycle
Where do files go?	Conventions and Layout
How do routes work?	Routing
How do controllers validate and render?	Controllers
How do records persist data?	Records
How do resources define responses?	Resources
How should authorization work?	Policies
How does runtime binding access work?	Adapters and Runtime
What commands are available?	CLI and Generators

Verification commands

For docs-only edits, run:

bun run docs:build

For framework behavior changes, also run the relevant tests:

bun test
bun run smoke