The best way to control Claude Code, Codex and more from any computer or phone

main
md 145 lines 6.32 KB
Rendered Raw
1 # Monorepo layout
2
3 ```text
4 my-app/
5 package.json workspace root: deploy scripts, the stack
6 pnpm-workspace.yaml packages: ["packages/*"]
7 tsconfig.json solution file: references every package + tsconfig.stack.json
8 tsconfig.stack.json alchemy.run.ts and root tests
9 alchemy.run.ts the stack: server Worker + web app
10 test/integ.test.ts deploys the stack and drives it
11 packages/
12 domain/ @acme/domain - the pure model (imports @alchemy.run/domain + effect only)
13 src/
14 Account/
15 Account.aggregate.ts
16 Account.id.ts
17 OpenAccount.command.ts command + its events + its rejections
18 WithdrawMoney.command.ts
19 NotOpen.rejection.ts shared by several commands
20 AccountSummary.view.ts
21 Statement.view.ts
22 Transfer/
23 Transfer.aggregate.ts
24 RequestTransfer.command.ts
25 ExecuteTransfer.saga.ts
26 TransferExecution.policy.ts
27 Fraud/
28 FraudCheck.external.ts declaration only
29 FraudReview.policy.ts
30 Ledger/
31 Ledger.projection.ts projection + its Live handler
32 LedgerStore.ts the port it writes through (+ a memory implementation)
33 Session.middleware.ts RpcMiddleware declaration + its error + client helper
34 CurrentActor.context.ts Domain.RequestContext
35 CustomerApi.api.ts
36 Bank.model.ts Domain.Model + the handlers Layer
37 test/Bank.story.test.ts
38 server/ @acme/server - hosting and adapters
39 src/
40 BankWorker.ts Cloudflare.Worker hosting the model
41 Session.ts SessionLive (verifies sessions), sign-in route
42 Fraud/SiftFraudCheck.ts FraudCheck.toLayer(...) - real adapter
43 Ledger/D1LedgerStore.ts LedgerStore over D1
44 test/CustomerApi.test.ts Api clients over in-memory hosting
45 web/ @acme/web - foldkit app
46 index.html
47 vite.config.ts
48 src/Bank.ts Model / Message / update / view / Commands / Subscriptions
49 src/entry.ts Runtime.run with the Api client as a resource
50 src/worker.ts serves the build, forwards /api to the server
51 test/Bank.test.ts foldkit stories
52 ```
53
54 ## What goes where
55
56 | Package | Holds | May import |
57 | --- | --- | --- |
58 | domain | every Domain building block, Apis, middleware declarations, request contexts, ports (`Context.Service` interfaces) with memory implementations, stories | `@alchemy.run/domain`, `@alchemy.run/domain/Story` (tests), `effect` |
59 | server | the Worker, `*Live` middleware, external system adapters, port implementations (D1, HTTP), event sources (Stripe webhooks), Api tests | domain, `@alchemy.run/cloudflare`, `@alchemy.run/cloudflare/Domain`, provider packages |
60 | web | the foldkit app and its Worker | domain (Api, ids, value schemas), `@alchemy.run/domain` (client protocols), `foldkit` |
61
62 Split a file when it mixes the two sides. For example, `Session.middleware.ts` (the domain declares it) and `Session.ts` (the server implements it).
63
64 More: [Project layout: Keep the model in its own package](https://alchemy.run/domain/project-layout#keep-the-model-in-its-own-package).
65
66 ## Package manifests
67
68 Each package exports its source files by path, so imports name the file they come from:
69
70 ```json
71 // packages/domain/package.json
72 {
73 "name": "@acme/domain",
74 "private": true,
75 "type": "module",
76 "sideEffects": false,
77 "exports": { "./*": "./src/*.ts" },
78 "scripts": { "test": "vitest run" },
79 "dependencies": { "alchemy": "^2", "effect": "^4" },
80 "devDependencies": { "@effect/vitest": "^4", "vitest": "^4" }
81 }
82 ```
83
84 ```ts
85 // packages/server/src/BankWorker.ts
86 import { Bank, BankHandlers } from "@acme/domain/Bank.model";
87 import { CustomerApi } from "@acme/domain/CustomerApi.api";
88 ```
89
90 Inside a package, import with relative paths and the `.ts` extension (`./Account.id.ts`). Across packages, import without the extension (`@acme/domain/Account/Account.id`). Don't add barrel files.
91
92 `server` depends on `@acme/domain` (`workspace:*`), `alchemy` and `effect`. `web` depends on `@acme/domain`, `alchemy`, `effect`, `foldkit` and `@effect/platform-browser`, with `vite`, `@foldkit/vite-plugin` and `vitest` as devDependencies. The root depends on `@acme/server` and `alchemy`.
93
94 ## TypeScript
95
96 Each package has its own `tsconfig.json`, with `noEmit`, `module: "Preserve"`, `moduleResolution: "Bundler"` and `allowImportingTsExtensions` (or `rewriteRelativeImportExtensions`). The root `tsconfig.json` is a solution file:
97
98 ```json
99 {
100 "files": [],
101 "references": [
102 { "path": "./packages/domain" },
103 { "path": "./packages/server" },
104 { "path": "./packages/web" },
105 { "path": "./tsconfig.stack.json" }
106 ]
107 }
108 ```
109
110 Type-check everything with `tsc -b`.
111
112 ## The stack
113
114 ```ts
115 // alchemy.run.ts
116 import * as Alchemy from "alchemy";
117 import * as Cloudflare from "@alchemy.run/cloudflare";
118 import * as Effect from "effect/Effect";
119 import BankWorker from "@acme/server/BankWorker";
120
121 export default Alchemy.Stack(
122 "Bank",
123 { providers: Cloudflare.providers(), state: Cloudflare.state() },
124 Effect.gen(function* () {
125 const bank = yield* BankWorker;
126 const app = yield* Cloudflare.Website.Foldkit("BankApp", {
127 rootDir: "packages/web",
128 main: "src/worker.ts",
129 env: { BANK: bank },
130 assets: { runWorkerFirst: ["/api", "/api/*"] },
131 });
132 return { api: bank.url.as<string>(), app: app.url.as<string>() };
133 }),
134 );
135 ```
136
137 Paths in resource props, such as D1 `migrations` and Website `rootDir`, resolve from the directory `alchemy deploy` runs in: the repo root.
138
139 More: [Cloudflare: Deploy it](https://alchemy.run/domain/cloudflare#deploy-it).
140
141 ## Several models
142
143 Each bounded context is its own domain package (`packages/banking`, `packages/lending`) with its own `*.model.ts`. They talk through policies that call each other's Apis or external system declarations, never by importing each other's aggregates. One server package can host several models; give each its own Worker or merge their layers into one.
144
145 More: [Project layout: Add a package per model](https://alchemy.run/domain/project-layout#add-a-package-per-model), [Domain Model: Keep one language per model](https://alchemy.run/domain/model#keep-one-language-per-model).