Conventions and Layout

Semitra is convention-driven. The app tree is not decoration. It is how the framework stays predictable.

Base classes

All core framework layers use Semitra-prefixed base classes:

SemitraController
SemitraRecord
SemitraResource
SemitraPolicy
SemitraJob
SemitraCache
SemitraStorage
SemitraEvents
SemitraChannel
SemitraMailer
SemitraMailbox

Application code usually defines local base classes that extend these once:

ApplicationController
ApplicationRecord
ApplicationResource
ApplicationPolicy
ApplicationJob
ApplicationMailer
ApplicationMailbox
ApplicationChannel

Conventional app tree

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

What each directory means

app/controllers handles requests and response orchestration.
app/models contains records and persistence rules.
app/resources defines external response shapes.
app/policies contains authorization and scoping logic.
app/jobs contains queue-backed work.
app/mailers and app/mailboxes handle outbound and inbound mail flows.
app/channels handles realtime subscriptions and broadcasting.
config/application.ts configures app runtime concerns like tenancy.
config/routes.ts defines the routing DSL.
db/migrate contains schema changes.
src/index.ts is the Worker entrypoint.

Filesystem-driven behavior

Semitra resolves the app root from convention:

a valid app root contains config/routes.ts
a valid app root contains src/index.ts
if you omit [app-root], the CLI resolves the nearest Semitra app or the single app inside ./apps

This is why the conventional layout matters to CLI commands such as dev, test, and db:migrate.

Runtime-safe rule

Semitra applications run in Cloudflare Workers. Keep that in mind when writing application code:

prefer Web Standard APIs
avoid Node-only runtime assumptions in app code
let subsystem packages own their responsibilities
let adapters bridge Cloudflare bindings into framework contracts