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, 07:15 UTC
| 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). |