The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: Project layout |
| 3 | description: How to lay out an @alchemy.run/domain project. One file per building block, named after its noun and its kind; folders per subdomain; a pure domain package, a server package that hosts it, and a foldkit web package, wired in one stack. |
| 4 | --- |
| 5 | |
| 6 | A domain grows into many small pieces: commands, events, rejections, views, policies. Lay them out so a file's name tells you what it holds before you open it, and so the model never depends on how it's hosted. |
| 7 | |
| 8 | ## Name a file after its noun and its kind |
| 9 | |
| 10 | Every file holds one building block, and its name is the block's name followed by its kind: |
| 11 | |
| 12 | ```text |
| 13 | WithdrawMoney.command.ts |
| 14 | Account.aggregate.ts |
| 15 | AccountSummary.view.ts |
| 16 | TransferExecution.policy.ts |
| 17 | ExecuteTransfer.saga.ts |
| 18 | Ledger.projection.ts |
| 19 | AccountCard.stream.ts |
| 20 | FraudCheck.external.ts |
| 21 | CustomerApi.api.ts |
| 22 | Bank.model.ts |
| 23 | ``` |
| 24 | |
| 25 | A model's other pieces follow the same rule: `Session.middleware.ts`, `CurrentActor.context.ts`, `Forbidden.rejection.ts`. Plain values, like `Money.ts`, and helpers, like `mustOwn.ts`, keep plain names. |
| 26 | |
| 27 | ## Keep a command with its events and rejections |
| 28 | |
| 29 | A command, the events it records and the rejections only it returns change together, so they share the command's file: |
| 30 | |
| 31 | ```typescript title="packages/domain/src/Account/WithdrawMoney.command.ts" |
| 32 | export class DailyLimitExceeded extends Domain.Rejection("DailyLimitExceeded", { |
| 33 | remaining: Cents, |
| 34 | }) {} |
| 35 | |
| 36 | export class MoneyWithdrawn extends Domain.Event("MoneyWithdrawn", { |
| 37 | amount: Cents, |
| 38 | balanceAfter: Cents, |
| 39 | }) {} |
| 40 | |
| 41 | /** Take money out of an account, within the balance and the daily limit. */ |
| 42 | export class WithdrawMoney extends Domain.Command("WithdrawMoney", { |
| 43 | ``` |
| 44 | |
| 45 | ## Give shared pieces their own file |
| 46 | |
| 47 | A rejection several commands return gets its own file, and so does an aggregate's id, next to the aggregate: |
| 48 | |
| 49 | ```typescript title="packages/domain/src/Account/WithdrawMoney.command.ts" |
| 50 | import { AccountId } from "./Account.id.ts"; |
| 51 | import { Frozen } from "./Frozen.rejection.ts"; |
| 52 | import { InsufficientFunds } from "./InsufficientFunds.rejection.ts"; |
| 53 | ``` |
| 54 | |
| 55 | ## Group files by subdomain |
| 56 | |
| 57 | Each folder is one part of the business, holding its aggregates and everything about them. The model sits beside the folders and lists what they hold: |
| 58 | |
| 59 | ```text |
| 60 | src/ |
| 61 | Account/ Account.aggregate.ts, WithdrawMoney.command.ts, Statement.view.ts, ... |
| 62 | Customer/ Customer.aggregate.ts, RegisterCustomer.command.ts, UsernameReservation.policy.ts, ... |
| 63 | Transfer/ Transfer.aggregate.ts, ExecuteTransfer.saga.ts, TransferExecution.policy.ts, ... |
| 64 | Fraud/ FraudCheck.external.ts, DailyOutflow.view.ts, FraudReview.policy.ts |
| 65 | Bank.model.ts |
| 66 | CustomerApi.api.ts |
| 67 | ``` |
| 68 | |
| 69 | ## Keep the model in its own package |
| 70 | |
| 71 | The domain package imports only `@alchemy.run/domain` and `effect`. Its stories run the whole model in memory, so it never needs a cloud account to test: |
| 72 | |
| 73 | ```text |
| 74 | packages/ |
| 75 | domain/ @bank/domain the model, its Apis and its stories |
| 76 | server/ @bank/server hosts the model and implements what it depends on |
| 77 | web/ @bank/web the foldkit app |
| 78 | alchemy.run.ts deploys the server and the web app together |
| 79 | ``` |
| 80 | |
| 81 | Other packages import its files by path, through its `exports`: |
| 82 | |
| 83 | ```typescript title="packages/server/src/BankWorker.ts" |
| 84 | import { Bank, BankHandlers } from "@bank/domain/Bank.model"; |
| 85 | ``` |
| 86 | |
| 87 | ## Host it from a server package |
| 88 | |
| 89 | The server package hosts the model on Durable Objects and implements what the domain only declares: middleware, external systems, stores, and where its telemetry goes. Swapping one implementation never touches the model: |
| 90 | |
| 91 | ```typescript title="packages/server/src/BankWorker.ts" |
| 92 | const BankLive = Layer.mergeAll( |
| 93 | SessionLive, |
| 94 | MfaChallengeLive, |
| 95 | Stripe.ConsumeEventsLive, |
| 96 | Observability, |
| 97 | ).pipe( |
| 98 | Layer.provideMerge(Bank.layer(BankHandlers)), |
| 99 | Layer.provideMerge(D1LedgerStore), |
| 100 | ``` |
| 101 | |
| 102 | ## Build the frontend in a web package |
| 103 | |
| 104 | The foldkit app imports the Api and its ids from the domain package, so the browser gets typed commands and live views with no hand-written client: |
| 105 | |
| 106 | ```typescript title="packages/web/src/entry.ts" |
| 107 | import { CustomerId } from "@bank/domain/Customer/Customer.id"; |
| 108 | import { CustomerApi } from "@bank/domain/CustomerApi.api"; |
| 109 | ``` |
| 110 | |
| 111 | ## Add a package per model |
| 112 | |
| 113 | A second bounded context, like lending next to banking, is a second domain package with its own model. The same server package can host both. See [`examples/cloudflare-domain`](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-domain) for the whole project. |