• Domain — entities, value objects, pure business logic. Zero dependencies on other layers, framework-agnostic.
• Application — use cases and handlers. Orchestrates domain models and outbound ports. Depends on Domain and application-owned port contracts.
• Infrastructure — DB, external APIs, queues, storage, and subprocess adapters. Implements outbound ports without owning use-case sequences.
• Entrypoints — receive external input or control across the system boundary and translate it into application calls.

server/
├── entrypoints/        # functions/ (server fns), queue/, scheduled/, middleware/ — transport only
├── application/        # message bus, handlers, registry
├── domain/             # messages/, models/, services/, errors/ — pure, framework-free
└── infrastructure/     # app-deps.ts, persistence/, auth/, resilience/, external clients

Db*

Standard, not fully practiced: repository interfaces belong in domain (older code keeps them in

infrastructure/persistence/repositories/interfaces.ts

). Apply to new code; don't churn existing files unprompted.

infrastructure/app-deps.ts

• createAppDeps(env, ctx)

  builds repos, services, gateways; services lazily memoized with

  once()

  .
• Bootstrap supplies

  AppDeps

  through request context or the project's composition middleware:

  context.deps.services.messageBus()

  .
• Handler signature:

  (message, deps: AppDeps) => Promise<TResult>

  .

• once()

  -memoized services must not capture transaction-scoped repos — they outlive any tx.
• Every entry is a client for something outside the process — database, queue, Durable Object, Workflow, external API. Group them:

  services

  (clients wrapped in our interfaces, e.g.

  queueClient(): IQueueClient

  ),

  clients

  (raw SDK clients),

  dos

  (Durable Object clients),

  workflows

  . Never a raw binding type in the interface.
• A rule is not a dep, data is not a dep. A policy object (

  DestinationPolicy

  ,

  RateTable

  , allow-lists, config-fed decisions) belongs in the domain as a pure function; the handler reads its inputs from the database via

  readDb

  and calls it. Named after a message kind (

  commands()

  ) is always wrong — name the capability.

// The shared function middleware owns error conversion.
export const createProduct = createServerFn({ method: 'POST' })
  .middleware([depsMiddleware, requireAuth])
  .validator(createProductSchema)
  .handler(async ({ data, context }) => {
    const result = await context.deps.services.messageBus().handle(
      createCommand('CreateProduct', { ...data, userId: context.user.id }),
    )
    return result
  })

1. Read its caller, shared contracts, and a comparable existing function.
2. Read

   src/start.ts

   and the registered error, authentication, and CSRF middleware.
3. Read the error payload module and any installed helper used by that middleware.
4. Confirm the success type, failure channel, and logging owner.
5. State material differences between the specification, reference code, and current project.

• Message-bus architecture: validate and authorize when required, build or parse a

  Command | Query | Event

  , await

  bus.handle(message)

  , then convert the result.
• Direct-handler architecture: validate and authorize when required, build typed input, await one application handler, then convert the result.
• Each platform boundary owns its delivery semantics: HTTP responses, queue acknowledgement, or scheduled invocation failures. Workflow orchestration owns durable step configuration.

Message bus:    Entrypoint → Command | Query | Event → Bus → Handler → Domain + Ports
Direct handler: Entrypoint → Typed input → Handler → Domain + Ports

1. Entrypoints are thin: validate when required → authorize when required → dispatch → convert.
2. Messages are pure data. No methods.
3. Handlers orchestrate. Zero business logic in handlers.
4. Domain is pure. No framework or infrastructure imports.
5. Dependencies flow inward — never the reverse.
6. Repository pattern: interface in domain, implementation in infrastructure.

id

id

• type: 'command' | 'event' | 'query'

  discriminant +

  name

  literal + optional

  userId

  (observability).

• id

  is

  uuid | externalMessageId

  . External ids are namespaced provider keys —

  stripe:event:evt_123

  — giving provider-keyed idempotency for webhooks. Factories (

  createCommand(...)

  ) default the uuid.

  [detect base.messages.ts]

  : current generation uses

  z.uuidv7()

  (time-ordered); older uses

  z.uuidv4()

  .

• [detect]

  message location: shared with client →

  packages/core/src/domain/**

  ; server-only →

  apps/<app>/src/server/domain/messages/

  .
• Payload IDs use branded schemas (

  UserIdSchema

  ,

  ProductIdSchema

  ); Zod v4 helpers (

  z.uuid()

  ,

  z.uuidv7()

  ,

  z.iso.datetime()

  ).

export const createProductSchema = baseCommandSchema.extend({
  name: z.literal('CreateProduct'),
  productName: z.string(),
  userId: UserIdSchema,
})

deps.uow.run(messageId, (repos, emit) => …)

emit

state

1. Claim receipt — insert

   message.id

   into

   message_receipts

   ; conflict →

   DuplicateMessageError

   .
2. Handler writes.
3. Persist emitted events to

   message_outbox

   — state change and events commit or roll back together.
4. Commit.

[detect unit-of-work implementation]

• D1: no interactive transactions — receipt + writes + outbox staged into one

  db.batch()

  , committed with retry; receipt UNIQUE violation →

  DuplicateMessageError

  .
• Postgres: real tx; Result-based with a rollback bridge (store

  Result.err

  →

  tx.rollback()

  → return stored err), branded

  Tx

  type, events collected via AsyncLocalStorage.

• No cross-boundary I/O inside a tx — no fetch/queue/R2 while holding a connection (Hyperdrive pool exhaustion).
• One aggregate per tx. Retry the whole UoW at the caller boundary. Never nest UoWs.
• Queries bypass UoW entirely; the read path may skip repositories — query handlers can do inline Drizzle

  select({...})

  → DTO. The DTO is a product resource, not a row. Do not leak a storage accident. Keep expensive associations off unless the caller asks.

1. Message receipts — automatic via UoW (above). Safe to retry commands / redeliver events.
2. External side effects — pass idempotency keys derived from stable operation properties:
   typescript

   await stripe.charges.create({ amount }, { idempotencyKey: `${runId}-${nodeId}` })

   Webhook-driven messages reuse the provider's key as the message id (

   stripe:event:evt_123

   ).
3. DB level — atomic insert, not check-then-insert:

   .onConflictDoNothing()

   /

   .onConflictDoUpdate()

   . No TOCTOU window.

• Closed method list:

  byId

  /

  findByX

  /

  insert

  /

  save

  /

  delete

  . No generic

  update(id, fields)

  .

• insert

  ≠

  save

  : insert fails on existing (

  AlreadyExists

  ); save is version-guarded (

  RevisionConflictError

  on stale version).
• Choose the insert type for each aggregate before you write the handler. Never check, then insert: two concurrent requests both pass the check.
  • Created once: a repeat is a mistake.

    insert

    fails with

    AlreadyExists

    , and the caller reports it.
  • Natural key, repeatable arrival: the same input must return the same aggregate, such as a file identified by its hash.

    insert

    runs

    ON CONFLICT (key) DO NOTHING RETURNING id

    , then reads the existing ID. It returns the ID and dispatches events only for a new row. The handler returns the ID and does not report "new" or "existing".
• Each repository defines one

  toDomain(row: DbRow): Entity

  mapper for persisted entities.

• toDomain

  builds the entity's plain data and passes it to

  Entity.restore(data)

  .

• toDomain

  maps field names and flat database rows to nested plain data. It does not validate or parse values.
• When flat database nullability conflicts with a domain union, use a narrow cast before

  restore

  ; the constructor enforces domain invariants.
• Writes map

  entity.toPlainObject()

  to the database insert or update shape inside the repository.
• Migrate old database values. Do not keep old-value conversion in

  toDomain

  after the migration.
• Drizzle, never raw SQL in handlers. Raw SQL only when Drizzle can't express the query — documented in the repo.

export class ProductRepository implements IProductRepository {
  async byId(id: ProductId, userId: UserId) {
    const row = await this.db.query.product.findFirst({
      where: and(eq(product.id, id), eq(product.userId, userId)),
    })
    if (!row) return Result.err(new EntityNotFoundError('Product', id))
    return Result.ok(this.toDomain(row))
  }

  private toDomain(row: DbProduct): Product {
    return Product.restore({
      id: row.id,
      name: row.name,
      state: { status: row.status },
    })
  }
}

sqliteTable('t', { ... }, (t) => [index('idx').on(t.col)])

• Base

  Entity

  :

  addEvent

  /

  collectEvents

  /

  clearEvents

  ; serialization via

  toPlainObject()

  .
• A persisted entity exposes

  toPlainObject(): EntityData

  and

  static restore(data: EntityData): Entity

  .

• restore

  accepts the exact type that

  toPlainObject

  returns.
• Use a private constructor. Validate key business invariants in the constructor or in one shared assertion that it calls.
• Do not repeat Zod validation from HTTP or I/O boundaries in the domain model.
• Do not repeat database type, nullability, or constraint checks in the domain model.
• Domain assertions augment boundary validation with rules that the type and database schema cannot express.

• create

  ,

  restore

  , and state transitions must use the same invariant validation.

• restore

  rebuilds domain state without emitting domain events.
• Domain entities must not import database types or expose

  fromPersistence

  and

  toPersistence

  methods.

• static create(...)

  — current generation returns

  Result<Entity, ValidationError>

  (throw = bug only); older generation throws on invariant violation.

export class Product extends Entity {
  private constructor(private readonly data: ProductData) {
    super()
    assertValidProduct(data)
  }

  static restore(data: ProductData): Product {
    return new Product(data)
  }

  toPlainObject(): ProductData {
    return { ...this.data }
  }
}

markLive(): Result<void, PlaybookEditError> {
  if (this.status === 'archived') return Result.err(new PlaybookEditError('archived'))
  this.status = 'live'
  this.updatedAt = new Date()
  return Result.ok()
}

/api

@<scope>/core/client

1. Ship the new field, tool, or shape next to the old one.
2. Mark the old one deprecated where a machine can see it:

   Deprecation

   +

   Sunset

   on HTTP,

   deprecated: true

   on an MCP tool or argument,

   @deprecated

   on an exported symbol.
3. State when it goes away (date, release, or no traffic for N days).
4. After that window, delete the old one in its own change.

/v1/

• Consumers must ignore unknown fields.
• The DTO hides storage accidents. Do not publish a persistence shape.
• Expensive associations are off by default. The caller opts in.
• Any operation exposed to code (MCP, HTTP, extension) needs a rate limit. Tighter limits on expensive work. Return

  Retry-After

  on 429. Keep a per-customer kill switch.

• Small user-scoped lists:

  ?page=1&limit=20

  (max 100) →

  { items, page, limit, total, hasNextPage, hasPrevPage }

  .
• Unbounded collections (job history, audit, MCP list tools): cursor +

  next

  token. Query is

  WHERE id > cursor ORDER BY id LIMIT n

  . Never offset those lists.

entrypoints/queue/

• Per-message Sentry isolation scope.

• classifyForRetry

  — typed errors decide retry vs park; explicit exponential backoff with caps.

• max_retries

  + DLQ configured in wrangler.jsonc; poison messages parked; duplicates acked as skip.

• Cron registry (

  entrypoints/scheduled/cron-registry.ts

  ) maps expressions → handlers; includes the outbox relay sweep.
• Cron does not retry. Each unit of work catches its own errors; one bad item must not kill the sweep.
• Local trigger:

  curl "http://localhost:8787/cdn-cgi/handler/scheduled"

  .

• One unit of work per step — steps are the retry boundary.
• Fetch-then-record: external call in one step, outcome recorded in the next; a retried step must never redo a committed effect.
• Intent → effect → outcome: mint durable intent (DB row) before the external effect.
• Map non-retryable typed errors to

  NonRetryableError

  ; internal vs external step configs carry the retry policies.

• Encrypted

  .env

  files are committed; private keys (

  .env.keys

  ) are gitignored. Scripts run under

  dotenvx run --

  .
• wrangler

  secrets.required

  manifests declare what prod needs.
• This is the secrets mechanism for these projects — it supersedes

  .dev.vars

  .

• List pagination on new list endpoints. Use the Published contracts rule: offset envelope for small user-scoped lists; cursor +

  next

  for unbounded collections.
• Repository interfaces in domain.
• Branded IDs on every message payload (legacy payloads have plain strings).