Building with @alchemy.run/domain

@alchemy.run/domain

models a backend as typed messages and pure state transitions. Commands are decided by aggregates, which record events. Views fold events into read models. Policies react to events. Sagas run long processes. Projections write outside the model, and queries serve what they wrote. The same model runs in memory for tests and on Cloudflare Durable Objects in production.

Docs: https://alchemy.run/domain, with every page listed in https://alchemy.run/llms.txt. Every section here and in the reference files ends with a More link to the docs page that covers it in depth. A complete reference project:

examples/cloudflare-domain

in the alchemy repo (a bank with a foldkit app).

Workflow

Work in this order. Each step has a reference file with templates.

Break the requirements down into building blocks. See references/modeling.md.
Lay out the monorepo: a domain package, a server package, a web package, with one kind-suffixed file per block. See references/layout.md.
Write each block from its template. See references/building-blocks.md.
Specify behavior with stories before and while you implement it. See references/testing.md.
Host the model on Cloudflare from the server package, export its traces, and deploy with one alchemy stack. See references/hosting.md.
Drive it from foldkit in the web package. See references/frontend.md.

More: Tutorial, part 1.

From requirements to building blocks

Read the requirements as a story of facts, and name each kind of thing you find:

A fact the business records, named in the past tense (
```
MoneyWithdrawn
```
): an Event.
A request to change something, named
```
<Verb><Noun>
```
(
```
WithdrawMoney
```
): a Command.
A way a request is refused (
```
InsufficientFunds
```
): a Rejection.
A thing whose rules must hold in one transaction (one account's balance): an Aggregate. It decides commands against its state.
A question someone asks (balance, statement, dashboard): a View, keyed by what it's about.
"Whenever X happens, do Y": a Policy.
A process with steps, waits and undo (move money: debit, credit, refund on failure): a Saga, started by a policy.
Something outside the model you call (fraud scoring, payments): an External System.
Writes to a store outside the model (a ledger table): a Projection. An ordered, readable log per key (account cards): a Stream that a projection appends to.
A question across keys, answered from that store (an account's ledger, paged; large withdrawals across all accounts, largest first): a Query. Never a hand-written route.
Who can do and see what: an Api listing commands and reads, with middleware (sessions, MFA) and each block authorizing itself: a command in
```
decide
```
, a view or stream in its Layer's
```
validate
```
, a query in its handler.

A rule that spans aggregates never becomes a cross-aggregate transaction. Give the invariant its own aggregate, keyed by what it protects (

UsernameClaim

keyed by username). Or reserve first and commit after, in a policy or saga, with a deadline for anything that waits.

More: What is Domain-Driven Design?, Domain Model.

Conventions

One block per file, named
<Noun>.<kind>.ts
. The kinds are

.aggregate

.command

.view

.policy

.saga

.projection

.stream

.query

.external

.api

and

.model

. Plus

.middleware

.context

and

.rejection

. An aggregate's id lives in

<Aggregate>.id.ts

next to it. Plain values (

Money.ts

) and helpers keep plain names.

A command file holds the command, the events it records, and the rejections only it returns. A rejection or event used by several commands gets its own file.
A block's implementation sits in its file (
```
TransferExecutionLive
```
in
```
TransferExecution.policy.ts
```
), unless it touches infrastructure. Then it lives in the server package.
Folders are subdomains (
```
Account/
```
,
```
Transfer/
```
). The model, Apis, middleware and request context sit at the package root.
The domain package imports only
@alchemy.run/domain
and
effect
. Cloudflare, Stripe, databases and HTTP session handling belong to the server package.
One domain package per model (bounded context). A second model is a second domain package; one server can host several.

More: Project layout.

Rules that keep a model correct

```
decide
```
is pure, or an
```
Effect.fn
```
that reads only what its command's middleware provides (
```
yield* CurrentActor
```
). It returns events or a rejection; it never performs I/O.
```
evolve
```
only applies an event to state. It never decides anything. It and
```
reply
```
are total: they cover every state and never fail, because
```
decide
```
already refused what can't happen. Keep a state the event can't follow (
```
s._tag === "Open" ? { ...s, balance: e.balanceAfter } : s
```
), never a guard that throws.
Events carry the outcome
```
decide
```
worked out (
```
balanceAfter
```
), so
```
evolve
```
copies it instead of repeating a rule.
Every rejection a command can return is listed in its
```
rejects
```
. Callers handle each one with
```
Effect.catchTag
```
.
Serve a store a projection writes through a
```
Domain.Query
```
on an Api, never a hand-written route: its handler checks the caller and scopes the rows it reads.
Clients never read an aggregate. Read through a view (one key, live), a stream, or a query; a query's handler may read an aggregate's latest state with
```
yield* Account
```
then
```
accounts.get(ref)
```
.
Policies and projections run at least once. Make their effects idempotent: commands sent from a handler get deterministic ids, and stores key rows by
```
stream:seq
```
.
Don't wait for a saga in a policy.
```
start
```
it, keyed by the aggregate it's about, and react to the events its steps record.
A handler resolves its dependencies once in
```
toLayer
```
and requires nothing per call.
Build one Layer and provide it once (
```
Layer.mergeAll
```
,
```
Layer.provide
```
). Never chain
```
Effect.provide
```
.
Never
```
throw
```
. Fail with tagged errors (
```
Domain.Rejection
```
,
```
Schema.TaggedError
```
).
Tracing is automatic. Record payload values only with
```
Effect.annotateCurrentSpan
```
in a handler: it lands on the engine's span for that handler. Make secrets
```
Schema.Redacted
```
, so they never reach a trace or a log.
Test what the model does, through stories: events, replies, rejections, views and saga outcomes. Don't test a saga's internal steps.

More: Domain Model: The aggregate decides, and everything commits at once, Cloudflare: Count on these guarantees.

Checklist for a change

Name the new facts, commands and rejections. Put each command in its own
```
<Command>.command.ts
```
with its events and rejections.
Add the command to its aggregate's
```
commands
```
, with a
```
decide
```
branch for it and an
```
evolve
```
branch for each event.
Update the views, policies and projections that care about the new events.
Expose it through an Api, if a client sends or reads it, with the middleware it needs, and give it a
```
{ description }
```
as its last argument.
Write stories for the happy path, every rejection, every policy reaction, and every query's authorization.
Run the domain package's tests, with one that expects
```
Domain.verify(Model)
```
to be empty. Then type-check the monorepo (
```
tsc -b
```
) and run the server and web tests.

alchemy-domain

NPX Install

Tags

SKILL.md Content