@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 113 lines 4.43 KB
Raw
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.