@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, 06:00 UTC

main
ts 2,113 lines 82.7 KB
Raw
1 /**
2 * The second talk: the tightest feedback loop you can give an agent. A chat
3 * app grows one piece at a time (Worker → Durable Object rooms over
4 * WebSockets → R2 uploads → a queue into Postgres on Neon), and the same
5 * end-to-end test follows it from the laptop, to a pull request's own copy,
6 * to staging and prod. `intro/build.ts loop` resolves this into
7 * `out/capture/loop/intro.json`; open it with `?deck=loop` in the presenter.
8 *
9 * Code comes from `snippets/chat/` and is type-checked; `*.error.ts` must fail.
10 */
11 import type { LoopPart, MiniGraph, MiniNode, PyramidLayer } from "../shared/intro.ts";
12 import type {
13 CodeSpec,
14 CommentSpec,
15 LoopSpec,
16 PyramidSpec,
17 RollSpec,
18 StepSpec,
19 TerminalSpec,
20 } from "./steps.ts";
21
22 // ── helpers ──────────────────────────────────────────────────────────────
23
24 const loop = (title: string, notes: string, lit?: LoopPart[], focus?: LoopPart[]): LoopSpec => ({
25 kind: "loop",
26 title,
27 notes,
28 lit,
29 focus: focus ?? lit,
30 frames: 20,
31 });
32
33 /** A code step from the chat app in `snippets/chat/`. */
34 const chat = (s: {
35 title: string;
36 notes: string;
37 snippet: string;
38 file: string;
39 group: string;
40 fontSize?: number;
41 regions?: string[];
42 omit?: string[];
43 fold?: string[];
44 marks?: CodeSpec["marks"];
45 diagram?: MiniGraph;
46 beside?: CodeSpec["beside"];
47 links?: CodeSpec["links"];
48 emphasize?: string[];
49 error?: CodeSpec["error"];
50 quiet?: boolean;
51 tints?: CodeSpec["tints"];
52 showRemoved?: boolean;
53 reel?: CodeSpec["reel"];
54 layer?: CodeSpec["layer"];
55 }): CodeSpec => ({
56 kind: "code",
57 group: s.group,
58 file: s.file,
59 title: s.title,
60 src: { snippet: `chat/${s.snippet}`, regions: s.regions ?? ["show"], omit: s.omit, fold: s.fold },
61 fontSize: s.fontSize,
62 marks: s.marks,
63 diagram: s.diagram,
64 beside: s.beside,
65 links: s.links,
66 emphasize: s.emphasize,
67 error: s.error,
68 quiet: s.quiet,
69 tints: s.tints,
70 showRemoved: s.showRemoved,
71 reel: s.reel,
72 layer: s.layer,
73 notes: s.notes,
74 frames: s.diagram ? 45 : undefined,
75 });
76
77 /** Code written inline (config files, the AWS versions). */
78 const inline = (s: Omit<CodeSpec, "kind" | "src"> & { code: string }): CodeSpec => {
79 const { code, ...rest } = s;
80 return { kind: "code", src: { code }, ...rest };
81 };
82
83 // ── terminal output, in the CLI's own colors ─────────────────────────────
84 const T = {
85 ok: "\x1b[38;5;113m",
86 soft: "\x1b[38;5;150m",
87 accent: "\x1b[38;5;173m",
88 grey: "\x1b[38;5;102m",
89 red: "\x1b[38;5;203m",
90 dim: "\x1b[2m",
91 bold: "\x1b[1m",
92 reset: "\x1b[0m",
93 };
94 const RULE = `${T.grey}${T.dim}${"─".repeat(52)}${T.reset}`;
95 const $ = (cmd: string) => `${T.dim}$${T.reset} ${cmd}`;
96 const res = (name: string, type: string) =>
97 `${T.bold}${name}${T.reset} ${T.dim}(${type})${T.reset}`;
98 /** The test run's bracketing phases: what it stands up before the tests and tears down after. */
99 const DEPLOYED = [
100 `${T.ok}${T.bold}▲ deploy${T.reset} ${T.dim}Chat → stage${T.reset} ${T.bold}test_sam${T.reset}`,
101 ` ${T.ok}+ Files + Messages + Db + Pool + Chat${T.reset}`,
102 ];
103 const DESTROYED = [
104 `${T.red}${T.bold}▼ destroy${T.reset} ${T.dim}Chat ← stage${T.reset} ${T.bold}test_sam${T.reset}`,
105 ` ${T.red}- Chat - Pool - Db - Messages - Files${T.reset}`,
106 ];
107 const PASSED = `${T.ok}✓${T.reset} a message reaches everyone in the room`;
108 const term = (s: Omit<TerminalSpec, "kind" | "lines"> & { lines: string[] }): TerminalSpec => ({
109 kind: "terminal",
110 ...s,
111 lines: s.lines.join("\n"),
112 });
113
114 // ── diagram helper (the shared-staging drawing) ─────────────────────────
115 const at = (
116 node: { id: string; title: string; color: string },
117 x: number,
118 y: number,
119 notes?: string[],
120 ): MiniNode => ({
121 ...node,
122 x,
123 y,
124 ...(notes ? { notes } : {}),
125 });
126
127 // ── the stack: what "the code" actually is ─────────────────────────────
128 const LAYER = {
129 infra: {
130 id: "infra",
131 title: "Infrastructure",
132 detail: "compute · databases · buckets · queues · networks",
133 color: "#8b9cf6",
134 },
135 config: {
136 id: "config",
137 title: "Configuration & policies",
138 detail: "IAM · env vars · secrets · DNS",
139 color: "#e0a86b",
140 },
141 api: {
142 id: "api",
143 title: "APIs & business logic",
144 detail: "domain models · rules · workflows",
145 color: "#a3c473",
146 },
147 web: { id: "web", title: "Frontend", detail: "websites · CDN · domains", color: "#e06c9f" },
148 } satisfies Record<string, PyramidLayer>;
149 const ALL_LAYERS = [LAYER.infra, LAYER.config, LAYER.api, LAYER.web];
150 const CHAT_LAYERS: PyramidLayer[] = [
151 { ...LAYER.infra, detail: "R2 bucket · queue · Neon Postgres" },
152 { ...LAYER.config, detail: "bindings · Hyperdrive · permissions" },
153 { ...LAYER.api, detail: "rooms · messages · history · uploads" },
154 { ...LAYER.web, detail: "the chat page, over WebSockets" },
155 ];
156 /** Observability: beside the pyramid, spanning every layer. */
157 const OBSERVE = {
158 title: "Observability",
159 lines: ["traces", "logs", "metrics", "dashboards", "alarms"],
160 color: "#56b6c2",
161 };
162 const pyramid = (
163 s: Omit<PyramidSpec, "kind" | "layers"> & { layers?: PyramidLayer[] },
164 ): PyramidSpec => ({
165 kind: "pyramid",
166 layers: ALL_LAYERS,
167 frames: 24,
168 ...s,
169 });
170
171 const opening: StepSpec[] = [
172 {
173 kind: "slide",
174 layout: "title",
175 title: "The tightest feedback loop from edit to production",
176 eyebrow: "Alchemy",
177 heading: "The tightest feedback loop\nfrom edit to production",
178 subtitle:
179 "Cloud programs composed from Layers:\ntype-checked, emulated locally, tested live, deployed per pull request",
180 footer: "alchemy.run",
181 notes:
182 "I'm Sam, I work on Alchemy. This talk is about what an AI agent needs to go fast and still ship things that work.",
183 },
184 ];
185
186 const theStack: StepSpec[] = [
187 pyramid({
188 title: "The whole app starts with the infrastructure it runs on",
189 layers: [LAYER.infra],
190 notes:
191 "Agents build, test and maintain whole apps, and a whole app is never just code. At the bottom is the infrastructure it runs on: compute, databases, buckets, queues, networks.",
192 }),
193 pyramid({
194 title: "…wired together with configuration and policies",
195 layers: [LAYER.infra, LAYER.config],
196 notes:
197 "On top of that is the glue: who can access what, environment variables, secrets, DNS records.",
198 }),
199 pyramid({
200 title: "…running the APIs and business logic",
201 layers: [LAYER.infra, LAYER.config, LAYER.api],
202 notes:
203 "Then the part we usually call the code: the APIs and business logic. The domain itself: its models, its rules, its workflows.",
204 }),
205 pyramid({
206 title: "…behind a frontend served from a CDN",
207 notes: "And at the top, the frontend people actually see, served from a CDN on a domain.",
208 }),
209 pyramid({
210 title: "…and in production, you have to see every layer",
211 pillar: OBSERVE,
212 notes:
213 "One more piece, and it isn't a layer. Production needs observability: traces, logs, metrics, and the dashboards and alarms that watch them. It's not on top or underneath. It runs beside the whole stack, because every layer feeds it. An agent has to get all of this right.",
214 }),
215 {
216 kind: "arch",
217 title: "We'll build a basic chat app on Cloudflare",
218 lanes: [
219 { label: "frontend", y: 250, color: "#e06c9f" },
220 { label: "APIs & logic", y: 565, color: "#a3c473" },
221 { label: "infrastructure", y: 890, color: "#8b9cf6" },
222 ],
223 nodes: [
224 { id: "browser", title: "Website", sub: "Vite chat page", color: "#8b9cf6", x: 900, y: 250 },
225 { id: "chat", title: "Chat", sub: "Cloudflare Worker", color: "#f38020", x: 900, y: 460 },
226 { id: "rooms", title: "Rooms", sub: "Durable Objects", color: "#e06c9f", x: 900, y: 670 },
227 { id: "files", title: "Files", sub: "R2 bucket", color: "#8b7cf6", x: 480, y: 890 },
228 {
229 id: "messages",
230 title: "Messages",
231 sub: "Cloudflare Queue",
232 color: "#e0a86b",
233 x: 900,
234 y: 890,
235 },
236 { id: "history", title: "History", sub: "Neon Postgres", color: "#34d399", x: 1320, y: 890 },
237 ],
238 edges: [
239 { from: "browser", to: "chat", label: "WebSocket" },
240 { from: "chat", to: "rooms", label: "join" },
241 { from: "chat", to: "files", label: "upload", elbow: true },
242 { from: "rooms", to: "messages", label: "append" },
243 { from: "messages", to: "history", label: "consume" },
244 ],
245 notes:
246 "Here's what we'll build, top to bottom, the same way the pyramid reads. A Vite site is the chat page, and it connects to a Worker over a WebSocket. The Worker hands each room to its own Durable Object and stores uploads in an R2 bucket. Each room appends its messages to a queue, which fills a Postgres database on Neon with the history. And all of it will be traced, so we can see it in production.",
247 },
248 ];
249
250 // ── other IaC frameworks: two programs ─────────────────────────────────────────────────
251 const SST_CONFIG = `const bucket = new sst.aws.Bucket("Files");
252
253 new sst.aws.Function("Upload", {
254 handler: "src/upload.handler",
255 link: [bucket],
256 url: true,
257 });`;
258 const SST_HANDLER = `import { Resource } from "sst";
259 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
260
261 const s3 = new S3Client({});
262
263 export const handler = async (event) => {
264 await s3.send(new PutObjectCommand({
265 Bucket: Resource.Files.name,
266 Key: event.queryStringParameters.name,
267 Body: event.body,
268 }));
269 return { statusCode: 201 };
270 };`;
271 const SST_BESIDE = { file: "src/upload.ts", src: { code: SST_HANDLER } };
272 /** What SST generates from the config, at the project root: one type for the whole app. */
273 const SST_ENV = `declare module "sst" {
274 export interface Resource {
275 "Files": { "name": string; "type": "sst.aws.Bucket" }
276 "Upload": { "name": string; "type": "sst.aws.Function" }
277 }
278 }`;
279 const sst = (s: Omit<CodeSpec, "kind" | "group" | "file" | "src" | "fontSize">): CodeSpec => ({
280 kind: "code",
281 group: "sst",
282 file: "sst.config.ts",
283 src: { code: SST_CONFIG },
284 fontSize: 22,
285 ...s,
286 });
287 const CUT = { under: "api", above: "runtime program", below: "infrastructure program" };
288 const UPLOAD = {
289 label: "upload a file",
290 items: {
291 infra: "Files bucket",
292 config: "s3:PutObject · $BUCKET",
293 api: "upload handler",
294 web: "upload button",
295 },
296 };
297 const twoPrograms: StepSpec[] = [
298 sst({
299 title: "With other IaC frameworks like SST, you write two programs",
300 beside: SST_BESIDE,
301 notes:
302 "So how would other infrastructure-as-code frameworks build this? Take one feature, uploading a file, with SST. sst.config.ts creates a bucket and a function and links them; it runs on your laptop at deploy time. The code that actually runs is a different file, bundled into Lambda. Two programs.",
303 }),
304 sst({
305 title: "They're joined only by a file path and a generated name",
306 beside: SST_BESIDE,
307 links: [{ from: '"src/upload.handler"', to: "export const handler", tone: "bad" }],
308 under: {
309 file: "sst-env.d.ts",
310 src: { code: SST_ENV },
311 label: "code generation",
312 links: [{ from: '"Files": {', to: "Resource.Files.name", tone: "bad" }],
313 },
314 notes:
315 "The two programs meet at a string with a file path in it, and at a name. To make that name type-safe, SST runs code generation: it writes sst-env.d.ts from the config, with a type for every resource in the app, and the handler reads Resource.Files.name through it.",
316 }),
317 sst({
318 title: "Code generation bridges the two, but it's an extra step to keep in sync",
319 beside: {
320 ...SST_BESIDE,
321 marks: [
322 {
323 kind: "underline",
324 find: "Resource.Files.name",
325 label: "only as fresh as the last codegen",
326 side: "right",
327 tone: "bad",
328 },
329 ],
330 },
331 marks: [
332 {
333 kind: "circle",
334 find: "link: [bucket]",
335 label: "grants s3:* on the bucket",
336 side: "right",
337 tone: "bad",
338 },
339 ],
340 under: {
341 file: "sst-env.d.ts",
342 src: { code: SST_ENV },
343 label: "code generation",
344 marks: [
345 {
346 kind: "underline",
347 find: "export interface Resource",
348 label: "one type for the whole app",
349 side: "right",
350 tone: "bad",
351 },
352 ],
353 },
354 notes:
355 "So the two programs are connected, but only through code generation. That's friction: a generated file that has to be regenerated whenever the config changes, and until it is, the handler is typed against a stale picture. It describes the whole app, not what this function can use. And link can't know what the handler does, so it grants s3:* on the bucket and every object in it, even though the handler only calls PutObject. That's a lot of machinery for an agent to keep in its head.",
356 }),
357 pyramid({
358 title: "SST, Pulumi, Terraform and the CDK all draw this line",
359 layers: CHAT_LAYERS,
360 cut: CUT,
361 notes:
362 "This isn't about SST. Pulumi, Terraform and the CDK all split an app the same way: a line through the middle of the stack. Infrastructure and policies below, in one program. The code that runs above, in another.",
363 }),
364 pyramid({
365 title: "…but every feature crosses it",
366 layers: CHAT_LAYERS,
367 cut: CUT,
368 slice: UPLOAD,
369 notes:
370 "But features don't live on one side of that line. Uploading a file needs a bucket, a permission and a variable, a handler, and a button. Every feature crosses the line, so every feature is split across two programs that have to agree.",
371 }),
372 pyramid({
373 title: "An agent editing the handler can't see below the line",
374 layers: CHAT_LAYERS,
375 cut: CUT,
376 slice: UPLOAD,
377 lit: ["api", "web"],
378 notes:
379 "And that's exactly where an agent gets lost. It edits the handler. The bucket, the permission and the variable are in the other program. The type checker can't connect them, so the agent guesses, and finds out in production.",
380 }),
381 pyramid({
382 title: "What if the feature owned both halves?",
383 layers: CHAT_LAYERS,
384 slice: { ...UPLOAD, label: "the Files module" },
385 notes:
386 "So erase the line. Instead of cutting the app horizontally into two programs, cut it vertically into modules. The Files module owns everything uploading needs: the bucket, the permission, and the code. And every module in the app will be a slice like that: a resource, a binding to it, and an API on top. We'll build each one exactly that way.",
387 }),
388 ];
389
390 const BRICKS = {
391 files: {
392 row: 0,
393 col: 1,
394 of: 2,
395 title: "Files",
396 detail: "R2 bucket · upload()",
397 color: "#8b7cf6",
398 },
399 database: {
400 row: 0,
401 col: 0,
402 of: 2,
403 title: "Database",
404 detail: "Neon · Hyperdrive",
405 color: "#34d399",
406 },
407 history: { row: 1, title: "History", detail: "append() · list()", color: "#e0a86b" },
408 rooms: { row: 2, title: "Rooms", detail: "Durable Objects · join()", color: "#e06c9f" },
409 chat: { row: 3, title: "Chat", detail: "Worker · routes", color: "#f38020" },
410 };
411 const ALL_BRICKS = [BRICKS.database, BRICKS.files, BRICKS.history, BRICKS.rooms, BRICKS.chat];
412 /** Beside each row, the code that puts that block on the ones beneath it. */
413 const PROVIDES = {
414 // Line one is Database's, line two is Files'; Files alone keeps its line.
415 files: { layer: "infra", text: "\nconst FilesR2 = Layer.effect(Files, …)", code: true },
416 bottom: {
417 layer: "infra",
418 text: "const DatabaseLive = Layer.unwrap(…)\nconst FilesR2 = Layer.effect(Files, …)",
419 code: true,
420 },
421 history: { layer: "config", text: "const HistoryLive = Layer.effect(History, …)", code: true },
422 rooms: { layer: "api", text: "const RoomsLive = Layer.effect(Rooms, …)", code: true },
423 chat: { layer: "web", text: 'export default Cloudflare.Worker("Chat", …)', code: true },
424 };
425 /** Beside each row on the last slide: the Worker's wiring, which reads top to bottom as the pyramid. */
426 const WIRED = [
427 { layer: "web", text: "Effect.provide(", code: true },
428 { layer: "api", text: " RoomsLive.pipe(", code: true },
429 { layer: "config", text: " Layer.provide(HistoryLive),", code: true },
430 { layer: "infra", text: " Layer.provide([DatabaseLive, FilesR2]),\n ),\n)", code: true },
431 ];
432 /** The chat app's pyramid, rebuilt from the modules implemented so far. */
433 const built = (
434 title: string,
435 bricks: typeof ALL_BRICKS,
436 notes: string,
437 side?: PyramidSpec["side"],
438 ): PyramidSpec => pyramid({ title, layers: CHAT_LAYERS, bricks, notes, side });
439
440 // ── modules: effectful constructors ─────────────────────────────────────
441 const FILES = { snippet: "Files.ts", file: "src/Files.ts", group: "files", fontSize: 25 };
442 const MODULE_BESIDE_CLASS = {
443 file: "the same shape, as a class",
444 src: {
445 code: `class FilesR2 {
446 private bucket: Bucket;
447
448 constructor() {
449 this.bucket = new Bucket("Files");
450 }
451
452 upload(name: string, body: string) {
453 return this.bucket.put(name, body);
454 }
455 }`,
456 },
457 };
458 /** History's dependencies, as a class receiving them. */
459 const HISTORY_BESIDE_CLASS = {
460 file: "the same shape, as a class",
461 src: {
462 code: `class HistoryLive {
463 constructor(private sql: Database) {}
464 }`,
465 },
466 };
467 const modules: StepSpec[] = [
468 chat({
469 ...FILES,
470 title: "In Alchemy, the Files module starts with the interface its callers use",
471 regions: ["service"],
472 notes:
473 "Here's that module in Alchemy. It starts with an interface: Files can upload. That's a Context.Service, a plain Effect service. Callers only ever see this.",
474 }),
475 chat({
476 ...FILES,
477 title: "Its implementation starts with a resource: an R2 bucket",
478 omit: ["service", "binding", "methods"],
479 emphasize: ["R2.Bucket("],
480 layer: "resource",
481 notes:
482 "The implementation is a Layer, and its constructor starts with what the module needs from the cloud: a resource, an R2 bucket. At deploy, this line creates it.",
483 }),
484 chat({
485 ...FILES,
486 title: "…adds a binding to it: read-write access…",
487 omit: ["service", "methods"],
488 layer: "binding",
489 notes:
490 "Then a binding: read-write access to that bucket. At deploy, it attaches the bucket to whatever Worker uses this module. At runtime, it hands back a client.",
491 }),
492 chat({
493 ...FILES,
494 title: "…and implements an API with it",
495 omit: ["service"],
496 layer: "api",
497 notes:
498 "Then the API: the methods the rest of the app calls, closing over that client. They're what run on each request. Resource, binding, API: one file holds the whole feature.",
499 }),
500 {
501 ...chat({
502 ...FILES,
503 title: "It's an effectful constructor, like a class constructor",
504 omit: ["service"],
505 quiet: true,
506 notes:
507 "If that shape looks familiar, it's a class: a constructor that creates what the object needs, and methods that use it. Files has no dependencies; its constructor creates the bucket itself, like new Bucket(). The difference is that this constructor is an Effect, so creating the bucket means declaring a real cloud resource, and the type system tracks everything it needs.",
508 }),
509 beside: MODULE_BESIDE_CLASS,
510 links: [
511 { from: 'R2.Bucket("Files")', to: 'new Bucket("Files")', tone: "construct" },
512 { from: "files.put(name, body)", to: "this.bucket.put(name, body)", tone: "runtime" },
513 ],
514 },
515 chat({
516 snippet: "FilesS3.ts",
517 file: FILES.file,
518 group: "files-s3",
519 fontSize: 22,
520 title: "On AWS, the constructor's binding becomes an IAM policy",
521 beside: {
522 file: "generated at deploy",
523 lang: "yaml",
524 src: {
525 code: `# IAM policy on the Worker's role
526 Effect: Allow
527 Action: s3:PutObject
528 Resource: arn:aws:s3:::chat-dev-sam-files/*`,
529 },
530 },
531 links: [{ from: "AWS.S3.PutObject(bucket)", to: "s3:PutObject", tone: "good" }],
532 notes:
533 "A quick detour to AWS, where this is easiest to see. Same module, backed by S3. The constructor asks for PutObject on this bucket, and at deploy that line becomes an IAM policy: exactly s3:PutObject, on exactly this bucket. Compare that with s3:* from link.",
534 }),
535 chat({
536 snippet: "FilesS3.ts",
537 file: FILES.file,
538 group: "files-s3",
539 fontSize: 22,
540 title: "…plus an environment variable with the bucket's name",
541 beside: {
542 file: "generated at deploy",
543 lang: "yaml",
544 src: {
545 code: `# IAM policy on the Worker's role
546 Effect: Allow
547 Action: s3:PutObject
548 Resource: arn:aws:s3:::chat-dev-sam-files/*
549
550 # Worker environment
551 $BUCKET_NAME: chat-dev-sam-files`,
552 },
553 },
554 links: [
555 { from: "AWS.S3.PutObject(bucket)", to: "s3:PutObject", tone: "good" },
556 { from: "putObject({", to: "$BUCKET_NAME", tone: "good" },
557 ],
558 notes:
559 "It also sets $BUCKET_NAME, so putObject knows where to write. Nobody writes the policy or the variable by hand. Delete the line and the permission goes with it, and anything that used it stops compiling. And callers don't change at all: it's still Files.",
560 }),
561 chat({
562 snippet: "FilesRead.error.ts",
563 file: FILES.file,
564 group: "files-read",
565 fontSize: FILES.fontSize,
566 title: "The types match the policy: ask for read-only and upload won't compile",
567 error: { pick: (lines) => lines.filter((line) => line.includes("'put'")).slice(0, 1) },
568 emphasize: ["R2.ReadBucket(bucket)"],
569 notes:
570 "Back on R2. Because every binding is a policy, the types the binding hands back are exactly what that policy allows. Ask for read-only access and you get a read-only client, with no put, so upload stops compiling. Least privilege isn't something to review after the fact. The type checker guarantees the policy and the code agree, and the agent finds out in milliseconds, in the editor.",
571 }),
572 ];
573
574 // ── composing modules as Layers ──────────────────────────────────────────
575 const HISTORY = { snippet: "History.ts", file: "src/History.ts", group: "history", fontSize: 19 };
576 const ROOM_FILE = { snippet: "Room.ts", file: "src/Room.ts", group: "room", fontSize: 22 };
577 const WORKER = { snippet: "ChatModules.ts", file: "src/Chat.ts", group: "chat", fontSize: 17 };
578 const compose: StepSpec[] = [
579 chat({
580 snippet: "DbSteps.ts",
581 file: "src/Db.ts",
582 group: "db",
583 fontSize: 25,
584 omit: ["pool", "connect", "ret"],
585 title: "The Database module starts with a Neon Postgres project",
586 layer: "resource",
587 notes:
588 "Same shape as Files: an interface, then a Layer. The interface is just a SQL client, called Database. The Layer's constructor declares what it needs, starting with a Neon Postgres project. Alchemy creates it at deploy and applies the migrations in ./migrations.",
589 }),
590 chat({
591 snippet: "DbSteps.ts",
592 file: "src/Db.ts",
593 group: "db",
594 fontSize: 25,
595 omit: ["connect", "ret"],
596 title: "Hyperdrive puts a connection pool in front of it",
597 layer: "resource",
598 notes:
599 "Workers are short-lived, so opening a Postgres connection on every request is slow. Hyperdrive keeps a pool of connections near the database. Its origin is the project's origin: one resource's output is the next one's input.",
600 }),
601 chat({
602 snippet: "DbSteps.ts",
603 file: "src/Db.ts",
604 group: "db",
605 fontSize: 25,
606 omit: ["ret"],
607 title: "Connect binds that pool to whichever Worker uses this module",
608 layer: "binding",
609 notes:
610 "Connect is a binding, like ReadWriteBucket was for Files. At deploy it adds the Hyperdrive pool to the Worker that ends up using this module. At runtime it hands back the pool's connection string.",
611 }),
612 chat({
613 snippet: "DbSteps.ts",
614 file: "src/Db.ts",
615 group: "db",
616 fontSize: 25,
617 title: "The constructor returns a SQL client for the rest of the app",
618 layer: "api",
619 notes:
620 "Then the constructor returns a Postgres Layer built from that connection string. That's why this is Layer.unwrap: the constructor's result is itself a Layer, and anything above it just asks for a SQL client. That's the whole Database module: a project, a pool, a binding, and a SQL client, in one file.",
621 }),
622 chat({
623 ...HISTORY,
624 title: "History starts as an empty Layer",
625 omit: ["service", "deps", "queue", "consume", "append", "list"],
626 notes:
627 "Chat history is the next module. Like the others, it's a Layer: a constructor that returns the methods the rest of the app calls. It starts empty.",
628 }),
629 chat({
630 ...HISTORY,
631 title: "It asks for the Database",
632 omit: ["service", "queue", "consume", "append", "list"],
633 beside: HISTORY_BESIDE_CLASS,
634 links: [{ from: "yield* Database", to: "private sql: Database", tone: "construct" }],
635 notes:
636 "Unlike Files, History doesn't create anything yet: its constructor asks for the Database module we just built. As a class, that would be a constructor parameter. It only names what it needs. It doesn't say which implementation, or where the database lives. That gets decided once, at the top.",
637 }),
638 chat({
639 ...HISTORY,
640 title: "list reads a room's messages from Postgres",
641 omit: ["service", "queue", "consume", "append"],
642 layer: "api",
643 notes: "The first method: list. One query against the database for a room's messages.",
644 }),
645 chat({
646 ...HISTORY,
647 title: "New messages go on a queue that History declares itself",
648 omit: ["service", "queueBinding", "consume", "append"],
649 layer: "resource",
650 notes:
651 "Messages arrive faster than we want to write them one at a time, so they go through a queue. History declares the queue right in its constructor: a resource, a Cloudflare Queue called Messages. Nothing else in the app knows it exists.",
652 }),
653 chat({
654 ...HISTORY,
655 title: "…with a binding that can send to it",
656 omit: ["service", "consume", "append"],
657 layer: "binding",
658 notes: "Then a binding: send access to that queue, and a client for it.",
659 }),
660 chat({
661 ...HISTORY,
662 title: "append puts a message on that queue",
663 omit: ["service", "consume"],
664 layer: "api",
665 notes:
666 "append sends a room name and the text onto the queue. That's what every chat room will call.",
667 }),
668 chat({
669 ...HISTORY,
670 title: "…and History consumes the queue into Postgres",
671 omit: ["service"],
672 layer: "binding",
673 notes:
674 "And History consumes its own queue, inserting each message into Postgres. Subscribing to a queue is an event source, and it's declared in the constructor like any binding: at deploy, it registers this Worker as the queue's consumer.",
675 }),
676 chat({
677 ...HISTORY,
678 title: "On Cloudflare, that line registers the Worker as the queue's consumer",
679 omit: ["service"],
680 emphasize: ["Queues.consumeQueueMessages", "Queues.WriteQueue(messages)"],
681 beside: {
682 file: "on Cloudflare, generated at deploy",
683 lang: "yaml",
684 src: {
685 code: `# Worker binding (send access)
686 - type: queue
687 name: Messages
688 queue_name: chat-dev-sam-messages
689
690 # Queue consumer
691 queue: chat-dev-sam-messages
692 script: chat-dev-sam-chat
693 settings:
694 batch_size: 10
695 max_retries: 3`,
696 },
697 },
698 links: [
699 { from: "consumeQueueMessages", to: "# Queue consumer", tone: "good" },
700 { from: "Queues.WriteQueue(messages)", to: "type: queue", tone: "good" },
701 ],
702 notes:
703 "Here's what those lines do on Cloudflare. consumeQueueMessages registers this Worker as the Messages queue's consumer, with its batch settings. WriteQueue adds a queue binding to the Worker, so it can send. No policies: on Cloudflare, access is the binding itself.",
704 }),
705 chat({
706 ...HISTORY,
707 title: "On AWS, the same line would grant three permissions and wire the trigger",
708 omit: ["service"],
709 emphasize: ["consumeQueueMessages"],
710 beside: {
711 file: "on AWS, generated at deploy",
712 lang: "yaml",
713 src: {
714 code: `# IAM policy on the Lambda's role
715 Effect: Allow
716 Action:
717 - sqs:ReceiveMessage
718 - sqs:DeleteMessage
719 - sqs:GetQueueAttributes
720 Resource: arn:aws:sqs:…:chat-dev-sam-messages
721
722 # Event source mapping
723 EventSourceArn: arn:aws:sqs:…:chat-dev-sam-messages
724 FunctionName: chat-dev-sam-history`,
725 },
726 },
727 links: [
728 { from: "consumeQueueMessages", to: "sqs:ReceiveMessage", tone: "good" },
729 { from: "consumeQueueMessages", to: "EventSourceArn", tone: "good" },
730 ],
731 notes:
732 "Now the same code on AWS, where the queue would be SQS and History would run in a Lambda. The same call does more: it grants exactly the three actions a consumer needs, on exactly this queue, and creates the event source mapping that invokes the Lambda with each batch. The trigger and its permissions exist exactly as long as that line does.",
733 }),
734 chat({
735 ...ROOM_FILE,
736 title: "Each room is a Durable Object that holds its sockets",
737 omit: ["history", "send"],
738 notes:
739 "Next, the chat rooms. Each room is its own Durable Object: one small stateful server per room name. It has the same shape as everything else, a constructor, then methods. Its fetch accepts a WebSocket, and each message goes to every socket in the room.",
740 }),
741 chat({
742 ...ROOM_FILE,
743 title: "…and each room appends its messages to History",
744 emphasize: ["yield* History", "history.append"],
745 notes:
746 "Each room asks for History and appends every message to it. The room doesn't know there's a queue or a database behind History. That's History's business. And like every other module, it doesn't say where History comes from; the Worker decides that.",
747 }),
748 chat({
749 ...WORKER,
750 title: "The Chat Worker wires up the whole stack of Layers",
751 emphasize: [
752 "yield* Room;",
753 "yield* History;",
754 "yield* Files;",
755 "Effect.provide(",
756 "HistoryLive.pipe(Layer.provide(DatabaseLive))",
757 " FilesR2,",
758 ],
759 notes:
760 "The Worker asks for the rooms, History and Files. join hands the WebSocket to that room's Durable Object, uploads go to Files, and history comes from History. At the bottom it wires the Layers: HistoryLive on DatabaseLive, and FilesR2. That one expression is the whole app's wiring, and it's the only place that decides which implementation each module gets. The rooms get History from here too.",
761 }),
762 chat({
763 snippet: "ChatMissing.error.ts",
764 file: WORKER.file,
765 group: WORKER.group,
766 fontSize: WORKER.fontSize,
767 title: "Forget a Layer and the Worker doesn't compile",
768 error: {
769 pick: (lines) =>
770 lines.filter((line) => line.startsWith("Type 'Files' is not assignable")).slice(0, 1),
771 below: true,
772 },
773 showRemoved: true,
774 notes:
775 "Leave FilesR2 out of the stack, and the Worker doesn't compile. The type says exactly which module is missing. That's the agent's fastest feedback: it can't deploy an app with a hole in it.",
776 }),
777 chat({
778 snippet: "ChatTraced.ts",
779 file: WORKER.file,
780 group: WORKER.group,
781 fontSize: WORKER.fontSize,
782 title: "Collecting every trace and log is one line in the Worker",
783 emphasize: ["Axiom.Telemetry("],
784 notes:
785 "One thing is missing for production: observability, the column beside the pyramid. Start with the simplest version. One line in the Worker: Axiom.Telemetry, pointed at an Axiom token and two datasets. It's an OpenTelemetry exporter, and every module is already written in Effect, so every step in the rooms, History, Files and Database becomes a span and every log line is shipped, with no changes to any of them.",
786 }),
787 ...[
788 {
789 omit: ["dashboard", "monitor"],
790 title: "Production also needs dashboards and alarms, so move it into a Layer",
791 notes:
792 "Collecting is only half of it. Production also needs something that plots the data and something that wakes you up. So move it into its own module: an Observability Layer. Its constructor declares where telemetry goes, two Axiom datasets and an ingest token that can only write to them, and returns the same Axiom.Telemetry.",
793 },
794 {
795 omit: ["monitor"],
796 title: "…with a dashboard that plots the errors…",
797 notes:
798 "Its constructor declares a dashboard, with a chart of errors over time. It's a resource like any other, so it's deployed and versioned with the app.",
799 },
800 {
801 omit: [],
802 title: "…and a monitor that alerts on them",
803 notes:
804 "And a monitor that fires when errors pass a threshold. In production, that alert is one more failure that goes back to the agent.",
805 },
806 ].map((step) =>
807 chat({
808 snippet: "Observability.ts",
809 file: "src/Observability.ts",
810 group: "observability",
811 fontSize: 22,
812 omit: step.omit,
813 title: step.title,
814 notes: step.notes,
815 }),
816 ),
817 chat({
818 snippet: "ChatObserved.ts",
819 file: WORKER.file,
820 group: WORKER.group,
821 fontSize: WORKER.fontSize,
822 title: "The Worker provides the Layer instead, beside the stack",
823 showRemoved: true,
824 notes:
825 "Back in the Worker, the Telemetry line becomes ObservabilityLive. Same traces and logs, and now the dashboard and the monitor deploy with the app.",
826 }),
827 {
828 kind: "dash",
829 title: "Deploy, and the dashboard is already there",
830 notes:
831 "Here's roughly what that gets you, mocked up. Deploy, and the dashboard exists: requests and errors over time, and every trace, broken down by module, because every module is already traced. Nobody clicked anything in a console.",
832 },
833 {
834 kind: "dash",
835 title: "When errors spike, the monitor fires, and the agent hears about it",
836 alert: true,
837 notes:
838 "And when something breaks in production, say uploads start timing out, the errors cross the threshold and the monitor fires. The trace points straight at Files.upload. That alert is one more failure that goes back to the agent, from production this time.",
839 },
840 ];
841
842 // ── the Stack: deploy, destroy, dev ──────────────────────────────────────
843 const program: StepSpec[] = [
844 chat({
845 snippet: "alchemy.run.ts",
846 file: "alchemy.run.ts",
847 group: "stack",
848 fontSize: 30,
849 omit: ["providers", "state", "chat", "ret"],
850 title: "That one program is deployed as a Stack",
851 notes:
852 "That one program needs an entry point: the Stack. It's an Effect program too: a name, some configuration, and a body.",
853 }),
854 chat({
855 snippet: "alchemy.run.ts",
856 file: "alchemy.run.ts",
857 group: "stack",
858 fontSize: 30,
859 omit: ["state", "chat", "ret"],
860 title: "providers says which clouds it can create things in",
861 notes:
862 "providers says which clouds this Stack can create resources in: Cloudflare and Neon. They're Layers too.",
863 }),
864 chat({
865 snippet: "alchemy.run.ts",
866 file: "alchemy.run.ts",
867 group: "stack",
868 fontSize: 30,
869 omit: ["chat", "ret"],
870 title: "state says where it records what it created",
871 notes:
872 "state says where the Stack records what it created, so the next deploy knows what already exists. Here, in Cloudflare.",
873 }),
874 chat({
875 snippet: "alchemy.run.ts",
876 file: "alchemy.run.ts",
877 group: "stack",
878 fontSize: 30,
879 omit: ["ret"],
880 title: "Its body yields the Chat Worker, and every Layer beneath it",
881 notes:
882 "The body yields the Chat Worker. That one line pulls in everything: the rooms, History, Files, Database, and all their resources and bindings.",
883 }),
884 chat({
885 snippet: "StackNoProviders.error.ts",
886 file: "alchemy.run.ts",
887 group: "stack",
888 fontSize: 30,
889 omit: ["ret"],
890 title: "Leave out the providers and the Stack doesn't compile",
891 error: {
892 pick: (lines) =>
893 lines.filter((line) => line.startsWith("Type 'Layer<never, never, never>'")).slice(0, 1),
894 below: true,
895 },
896 showRemoved: true,
897 notes:
898 "Take the providers away and it's a type error. Because the body yields the Chat Worker, the Stack's type knows every kind of resource underneath it: a Cloudflare Worker, an R2 bucket, a queue, a Neon project. So it knows exactly which providers it needs, and it won't compile until you configure all of them.",
899 }),
900 chat({
901 snippet: "alchemy.run.ts",
902 file: "alchemy.run.ts",
903 group: "stack",
904 fontSize: 30,
905 emphasize: ["return { url"],
906 title: "…and returns what the app exposes: its URL",
907 notes:
908 "And it returns the Stack's outputs, here the Worker's URL, so deploys and tests can find the app.",
909 }),
910 term({
911 group: "cli",
912 title: "alchemy deploy plans what has to change",
913 lines: [
914 $("alchemy deploy"),
915 `${T.ok}✓${T.reset} Plan ready`,
916 RULE,
917 `${T.accent}${T.bold}Deploy${T.reset}${T.dim} · ${T.reset}${T.ok}10 to create${T.reset}${T.dim} · ${T.reset}${T.soft}6 bindings${T.reset}`,
918 ``,
919 `${T.ok}+${T.reset} ${res("Files", "Cloudflare.R2.Bucket")}`,
920 `${T.ok}+${T.reset} ${res("Messages", "Cloudflare.Queues.Queue")}`,
921 `${T.ok}+${T.reset} ${res("Db", "Neon.Project")}`,
922 `${T.ok}+${T.reset} ${res("Pool", "Cloudflare.Hyperdrive")}`,
923 `${T.ok}+${T.reset} ${res("Traces", "Axiom.Dataset")}`,
924 `${T.ok}+${T.reset} ${res("Logs", "Axiom.Dataset")}`,
925 `${T.ok}+${T.reset} ${res("Ingest", "Axiom.ApiToken")}`,
926 `${T.ok}+${T.reset} ${res("Dashboard", "Axiom.Dashboard")}`,
927 `${T.ok}+${T.reset} ${res("Errors", "Axiom.Monitor")}`,
928 `${T.ok}+${T.reset} ${res("Chat", "Cloudflare.Worker")}`,
929 ` ${T.ok}+${T.reset} ${T.soft}Cloudflare.R2.ReadWrite(Files)${T.reset}`,
930 ` ${T.ok}+${T.reset} ${T.soft}Cloudflare.Queues.Write(Messages)${T.reset}`,
931 ` ${T.ok}+${T.reset} ${T.soft}Cloudflare.Queues.Consume(Messages)${T.reset}`,
932 ` ${T.ok}+${T.reset} ${T.soft}Cloudflare.Hyperdrive.Connect(Pool)${T.reset}`,
933 ` ${T.ok}+${T.reset} ${T.soft}Cloudflare.DurableObject(Room)${T.reset}`,
934 ` ${T.ok}+${T.reset} ${T.soft}Axiom.Telemetry(Ingest)${T.reset}`,
935 ],
936 notes:
937 "alchemy deploy first compares that program with what's in the cloud and plans what has to change. Nothing exists yet, so everything is a create: every resource, every binding between them, and the dashboard and monitor that watch them.",
938 }),
939 term({
940 group: "cli-apply",
941 title: "…then makes the cloud match, in dependency order",
942 lines: [$("alchemy deploy"), `${T.ok}✓${T.reset} Plan ready`, RULE],
943 fresh: 0,
944 progress: {
945 rows: [
946 { name: "Files", type: "Cloudflare.R2.Bucket", from: 4, to: 26 },
947 { name: "Messages", type: "Cloudflare.Queues.Queue", from: 6, to: 24 },
948 { name: "Db", type: "Neon.Project", from: 4, to: 50 },
949 { name: "Traces", type: "Axiom.Dataset", from: 5, to: 18 },
950 { name: "Logs", type: "Axiom.Dataset", from: 5, to: 20 },
951 { name: "Ingest", type: "Axiom.ApiToken", from: 21, to: 32 },
952 { name: "Dashboard", type: "Axiom.Dashboard", from: 21, to: 36 },
953 { name: "Errors", type: "Axiom.Monitor", from: 22, to: 38 },
954 { name: "Pool", type: "Cloudflare.Hyperdrive", from: 51, to: 68 },
955 { name: "Chat", type: "Cloudflare.Worker", from: 69, to: 96 },
956 { name: "Cloudflare.R2.ReadWrite(Files)", binding: true, from: 97, to: 104 },
957 { name: "Cloudflare.Queues.Write(Messages)", binding: true, from: 97, to: 105 },
958 { name: "Cloudflare.Queues.Consume(Messages)", binding: true, from: 98, to: 108 },
959 { name: "Cloudflare.Hyperdrive.Connect(Pool)", binding: true, from: 98, to: 106 },
960 { name: "Cloudflare.DurableObject(Room)", binding: true, from: 99, to: 107 },
961 { name: "Axiom.Telemetry(Ingest)", binding: true, from: 99, to: 109 },
962 ],
963 done: [
964 RULE,
965 `${T.ok}Stack deployed (10/10)${T.reset} ${T.dim}{ url: "https://chat-dev-sam.workers.dev" }${T.reset}`,
966 ].join("\n"),
967 at: 112,
968 },
969 notes:
970 "Then it does it. Everything that doesn't depend on anything starts at once: the bucket, the queue, the Neon project, the Axiom datasets. The token, dashboard and monitor wait for the datasets. Hyperdrive waits for the database. The Worker waits for all of it, and then its bindings attach. At the end, the Stack's outputs: the app's URL.",
971 }),
972 term({
973 group: "cli",
974 title: "Running it again changes nothing",
975 lines: [
976 $("alchemy deploy"),
977 `${T.ok}✓${T.reset} Plan ready`,
978 RULE,
979 `${T.dim}No changes${T.reset}`,
980 ],
981 notes:
982 "Run it again and nothing happens. The program describes the end state, not the steps to get there, so it's always safe to run. An agent can't break anything by deploying twice.",
983 }),
984 term({
985 group: "cli",
986 title: "alchemy destroy removes every piece of it",
987 lines: [
988 $("alchemy destroy"),
989 `${T.red}-${T.reset} ${res("Chat", "Cloudflare.Worker")} deleted`,
990 `${T.red}-${T.reset} ${res("Pool", "Cloudflare.Hyperdrive")} deleted`,
991 `${T.red}-${T.reset} ${res("Errors", "Axiom.Monitor")} deleted`,
992 `${T.red}-${T.reset} ${res("Dashboard", "Axiom.Dashboard")} deleted`,
993 `${T.red}-${T.reset} ${res("Ingest", "Axiom.ApiToken")} deleted`,
994 `${T.red}-${T.reset} ${res("Logs", "Axiom.Dataset")} deleted`,
995 `${T.red}-${T.reset} ${res("Traces", "Axiom.Dataset")} deleted`,
996 `${T.red}-${T.reset} ${res("Db", "Neon.Project")} deleted`,
997 `${T.red}-${T.reset} ${res("Messages", "Cloudflare.Queues.Queue")} deleted`,
998 `${T.red}-${T.reset} ${res("Files", "Cloudflare.R2.Bucket")} deleted`,
999 RULE,
1000 `${T.ok}Stack destroyed (10/10)${T.reset}`,
1001 ],
1002 notes:
1003 "And destroy removes everything the Stack created, in reverse dependency order: the Worker first, then what it used, down to the bucket, the queue and the database. Nothing left behind to clean up by hand.",
1004 }),
1005 term({
1006 group: "cli",
1007 title: "alchemy dev runs the same program on your machine",
1008 lines: [
1009 $("alchemy dev"),
1010 `${T.ok}✓${T.reset} ${res("Chat", "Cloudflare.Worker")} ${T.dim}→${T.reset} http://localhost:1337`,
1011 `${T.dim}watching for changes…${T.reset}`,
1012 ],
1013 notes:
1014 "And alchemy dev runs the same program locally, with emulated Cloudflare services. Because the whole app is one declarative program, an agent can stand it up, tear it down, and run it locally, all by itself. Which brings us back to the question we started with: how does it know the app works?",
1015 }),
1016 ];
1017
1018 // ── act 0: the loop, introduced one piece at a time ─────────────────────
1019 /** A map step that draws only `show`, everything lit. */
1020 const reveal = (title: string, notes: string, show: LoopPart[], focus?: LoopPart[]): LoopSpec => ({
1021 kind: "loop",
1022 title,
1023 notes,
1024 show,
1025 focus,
1026 frames: 30,
1027 });
1028 const MACHINE: LoopPart[] = ["edit", "types", "local", "live", "feedback"];
1029 const PULL: LoopPart[] = ["push", "pr", "prTest", "comment"];
1030 const MAIN: LoopPart[] = ["merge", "staging", "stagingTest", "prod"];
1031 const theLoop: StepSpec[] = [
1032 reveal(
1033 "So an agent can change any part of this app in seconds",
1034 "Here's the agent. It can change any layer of this app in seconds, and it'll happily tell you it's done. How does it actually find out?",
1035 ["edit"],
1036 ),
1037 reveal(
1038 "Getting that change safely into production takes much longer",
1039 "Over here is production. Between the two is everything that decides whether that edit was right. Each of those steps is feedback, and the agent can only move as fast as the slowest one it has to wait for.",
1040 ["edit", "prod"],
1041 ),
1042 reveal(
1043 "The type checker answers first, and now it sees every layer",
1044 "The first check is the one we just built: the type checker. Because the whole app is one program, it covers the bucket, the permission and the code, in milliseconds, pointing at the exact line. Every failure goes back to the agent, which fixes it and tries again.",
1045 ["edit", "types", "feedback", "prod"],
1046 ["types"],
1047 ),
1048 reveal(
1049 "Tests on emulated services answer in seconds",
1050 "Next, tests that run the whole app on your machine, against emulated cloud services. Seconds, free, and the agent can run them after every change.",
1051 ["edit", "types", "local", "feedback", "prod"],
1052 ["local"],
1053 ),
1054 reveal(
1055 "Tests against the real cloud catch what emulators miss",
1056 "Then the same tests against the real cloud, in a stage of their own. Slower, but that's where permissions, networking and real service behavior show up.",
1057 [...MACHINE, "prod"],
1058 ["live"],
1059 ),
1060 reveal(
1061 "A pull request gets its own copy of the app to test",
1062 "When it's green locally, the agent opens a pull request. CI deploys a copy of the app just for that PR, runs the same tests, and comments with a link to try it.",
1063 [...MACHINE, ...PULL, "prod"],
1064 PULL,
1065 ),
1066 reveal(
1067 "Merging runs the same tests again on staging",
1068 "Merging deploys staging and runs the same tests one more time. Only a green staging goes to prod. That's every step between an edit and production: your machine, the pull request, and main. We have the first box. The rest of this talk builds the others.",
1069 [...MACHINE, ...PULL, ...MAIN],
1070 ["merge", "staging", "stagingTest"],
1071 ),
1072 ];
1073
1074 // ── act 3: one test for the whole app, local or live ─────────────────────
1075 const TEST = { snippet: "chat.test.ts", file: "test/chat.test.ts", group: "test", fontSize: 27 };
1076 const LOCAL_RUN = [
1077 $("LOCAL=1 pnpm test"),
1078 `${T.ok}${T.bold}▲ start${T.reset} ${T.dim}Chat →${T.reset} ${T.bold}http://localhost:1337${T.reset}`,
1079 PASSED,
1080 `${T.red}${T.bold}▼ stop${T.reset} ${T.dim}Chat${T.reset}`,
1081 ];
1082 const tests: StepSpec[] = [
1083 loop(
1084 "Next, tests that prove the whole app works",
1085 "Types say the pieces fit together. They can't say that a message Alice sends actually reaches Bob. For that the agent needs tests that run the whole app, on its machine and in the real cloud.",
1086 ["local", "live"],
1087 ),
1088 chat({
1089 ...TEST,
1090 title: "A test deploys the whole Stack first, and destroys it after",
1091 omit: ["dev", "test", "stage"],
1092 notes:
1093 "An end-to-end test starts by deploying the same Stack. deploy(Stack) runs once for the file, so every test shares one deployment, and destroy(Stack) tears it all down when the file is done.",
1094 }),
1095 chat({
1096 ...TEST,
1097 title: "Then it talks to the app the way a user would",
1098 omit: ["dev", "history", "stage"],
1099 notes:
1100 "Then it uses the app like a person would. Alice and Bob join the lobby over WebSockets, Alice says hi, Bob hears it. That goes through the Worker and the Durable Object.",
1101 }),
1102 chat({
1103 ...TEST,
1104 title: "It checks the queue and the database too",
1105 omit: ["dev", "stage"],
1106 notes:
1107 "And the message should land in history, which means it went through the queue, the consumer and Postgres. One test covers every piece of the app.",
1108 }),
1109 term({
1110 group: "test-run",
1111 title: "pnpm test runs it against the real cloud",
1112 lines: [
1113 $("pnpm test"),
1114 ...DEPLOYED,
1115 ``,
1116 PASSED,
1117 ``,
1118 ...DESTROYED,
1119 ``,
1120 `${T.ok}1 passed${T.reset}`,
1121 ],
1122 notes:
1123 "Run it, and the test deploys the whole app to a stage of its own, test_sam, in the real cloud: real Workers, real queues, a real Neon database. The test runs against it, and afterwards every resource is destroyed. Nothing shared with your dev stage or anyone else's, and nothing left behind.",
1124 }),
1125 chat({
1126 snippet: "chat-dev.test.ts",
1127 file: TEST.file,
1128 group: "test-dev",
1129 fontSize: 30,
1130 title: "dev: true runs the same Stack on emulated services",
1131 emphasize: ["dev: true"],
1132 notes:
1133 "First box: emulated. Set dev to true and the test runs the whole Stack on emulated services: workerd for the Worker, Durable Objects, R2 and queues, locally. Same Stack, same test.",
1134 }),
1135 chat({
1136 snippet: "chat.test.ts",
1137 file: TEST.file,
1138 group: "test-dev",
1139 fontSize: 30,
1140 regions: ["make"],
1141 omit: ["stage"],
1142 title: "An environment variable decides where it runs",
1143 emphasize: ["dev: !!process.env.LOCAL"],
1144 notes:
1145 "Make it an environment variable, and the agent picks: LOCAL=1 while it iterates, and without it, the real cloud.",
1146 }),
1147 term({
1148 group: "test-run",
1149 title: "LOCAL=1 runs it on emulated services",
1150 lines: [...LOCAL_RUN],
1151 notes:
1152 "With LOCAL=1, the same test starts the whole app on emulated services on your machine, runs, and stops it. It's fast and free, so the agent can run it after every change.",
1153 }),
1154 term({
1155 group: "test-run",
1156 title: "Emulated for speed, live for the real thing",
1157 lines: [...LOCAL_RUN, ``, $("pnpm test"), ...DEPLOYED, PASSED, ...DESTROYED],
1158 fresh: 7,
1159 notes:
1160 "Without it, the same command runs live. Both are one command away: emulated after every change, live to catch what emulation can't, like permissions and real network behavior.",
1161 }),
1162 ];
1163
1164 // ── act 4: every pull request gets its own copy ──────────────────────────
1165 const PR_YAML = `on: pull_request
1166
1167 jobs:
1168 test:
1169 runs-on: ubuntu-latest
1170 env:
1171 STAGE: pr-\${{ github.event.number }}
1172 steps:
1173 - uses: actions/checkout@v5
1174 - run: pnpm install
1175 - run: pnpm test`;
1176 const PR_YAML_CLOSE = `on:
1177 pull_request:
1178 types: [opened, synchronize, closed]
1179
1180 jobs:
1181 test:
1182 if: github.event.action != 'closed'
1183 runs-on: ubuntu-latest
1184 env:
1185 STAGE: pr-\${{ github.event.number }}
1186 steps:
1187 - uses: actions/checkout@v5
1188 - run: pnpm install
1189 - run: pnpm test
1190
1191 cleanup:
1192 if: github.event.action == 'closed'
1193 runs-on: ubuntu-latest
1194 steps:
1195 - run: pnpm alchemy destroy --stage pr-\${{ github.event.number }}`;
1196 const ci: StepSpec[] = [
1197 loop(
1198 "Green on your machine, the agent opens a pull request",
1199 "Once the tests pass locally, the agent pushes and opens a pull request. Now we walk the pull request lane, left to right.",
1200 ["push"],
1201 ),
1202 loop(
1203 "CI deploys a copy of the app just for that pull request",
1204 "First box: deploy. CI can't use the agent's copy of the app, so it deploys one of its own, just for pull request 42.",
1205 ["pr"],
1206 ),
1207 term({
1208 group: "stages",
1209 title: "A stage gives it a complete, isolated copy of the app",
1210 lines: [
1211 $("alchemy deploy --stage pr-42"),
1212 `${T.accent}${T.bold}Deploy${T.reset}${T.dim} · ${T.reset}${T.ok}6 to create${T.reset}`,
1213 ``,
1214 `${T.ok}+${T.reset} ${res("Room", "Cloudflare.DurableObject")}`,
1215 `${T.ok}+${T.reset} ${res("Files", "Cloudflare.R2.Bucket")} ${T.soft}chat-pr-42-files${T.reset}`,
1216 `${T.ok}+${T.reset} ${res("Messages", "Cloudflare.Queues.Queue")} ${T.soft}chat-pr-42-messages${T.reset}`,
1217 `${T.ok}+${T.reset} ${res("Db", "Neon.Project")} ${T.soft}chat-pr-42-db${T.reset}`,
1218 `${T.ok}+${T.reset} ${res("Pool", "Cloudflare.Hyperdrive")} ${T.soft}chat-pr-42-pool${T.reset}`,
1219 `${T.ok}+${T.reset} ${res("Chat", "Cloudflare.Worker")} ${T.soft}chat-pr-42-chat${T.reset}`,
1220 ],
1221 notes:
1222 "A stage is a name, like dev_sam, test_sam or pr-42. Every resource's physical name includes it, and every stage keeps its own state. Deploy a new stage and you get a whole new copy of the app.",
1223 }),
1224 ];
1225
1226 // ── act 5: shared infrastructure, by reference ───────────────────────────
1227 const DB_FILE = { snippet: "DbBranch.ts", file: "src/Db.ts", group: "db", fontSize: 25 };
1228 const staging = (id: string, title: string, color: string, x: number) =>
1229 at({ id, title, color }, x, 110);
1230 const pr = (id: string, title: string, color: string, x: number, y: number) =>
1231 at({ id, title, color }, x, y);
1232 const SHARED: MiniGraph = {
1233 nodes: [
1234 staging("sChat", "Chat", "#f38020", 360),
1235 pr("w41", "pr-41", "#f38020", 120, 330),
1236 pr("w42", "pr-42", "#f38020", 360, 330),
1237 pr("w43", "pr-43", "#f38020", 600, 330),
1238 at({ id: "sDb", title: "Db", color: "#34d399" }, 360, 500),
1239 pr("d41", "pr-41", "#34d399", 120, 710),
1240 pr("d42", "pr-42", "#34d399", 360, 710),
1241 pr("d43", "pr-43", "#34d399", 600, 710),
1242 ],
1243 edges: [
1244 { from: "sChat", to: "w41" },
1245 { from: "sChat", to: "w42" },
1246 { from: "sChat", to: "w43" },
1247 { from: "sDb", to: "d41" },
1248 { from: "sDb", to: "d42" },
1249 { from: "sDb", to: "d43" },
1250 ],
1251 labels: [
1252 { text: "staging", x: 100, y: 122, tone: "construct" },
1253 { text: "staging", x: 100, y: 512, tone: "construct" },
1254 ],
1255 };
1256 const shared: StepSpec[] = [
1257 chat({
1258 snippet: "Db.ts",
1259 file: DB_FILE.file,
1260 group: DB_FILE.group,
1261 fontSize: DB_FILE.fontSize,
1262 title: "But a new database for every pull request starts empty",
1263 notes:
1264 "A full copy per PR is great for isolation, but look at the Database Layer: every stage creates a brand new Neon project, with no data in it. Real apps need realistic data to test against, and creating a database per PR is slow and costs money.",
1265 quiet: true,
1266 }),
1267 chat({
1268 ...DB_FILE,
1269 title: "A pull request branches staging's database instead",
1270 notes:
1271 "For a PR stage, reference staging's project with ref, which reads it from staging's state without owning it, and create a Neon branch in it. A branch is a copy-on-write fork of staging's data, ready in about a second.",
1272 }),
1273 chat({
1274 snippet: "ChatPreview.ts",
1275 file: WORKER.file,
1276 group: "preview",
1277 fontSize: 27,
1278 regions: ["top", "bottom"],
1279 title: "The Worker does the same, as a preview of staging's Worker",
1280 emphasize: ["preview", "Worker.ref"],
1281 notes:
1282 "Same idea for the Worker. In a PR stage, it's uploaded as a preview of staging's Worker, with its own URL and its own Durable Object state, instead of a whole new Worker.",
1283 }),
1284 {
1285 kind: "code",
1286 group: "shared",
1287 title: "So staging is shared, and every pull request branches off it",
1288 src: {
1289 code: `Cloudflare.Worker.ref("Chat", { stage: "staging" })
1290 Neon.Project.ref("Db", { stage: "staging" })`,
1291 },
1292 fontSize: 26,
1293 diagram: SHARED,
1294 quiet: true,
1295 frames: 60,
1296 notes:
1297 "So staging is the one shared environment. Each PR gets a preview of its Worker and a branch of its database: realistic, isolated, and cheap enough to make for every PR.",
1298 },
1299 loop(
1300 "With its own preview, the pull request is ready to test",
1301 "Back to the map. The pull request has its own preview now, branched from staging. Next box: test it in CI.",
1302 ["prTest"],
1303 ),
1304 inline({
1305 group: "ci",
1306 file: ".github/workflows/pr.yml",
1307 lang: "yaml",
1308 fontSize: 30,
1309 title: "CI runs the same tests against that preview",
1310 code: PR_YAML,
1311 emphasize: ["STAGE: pr-", "pnpm test"],
1312 notes:
1313 "And CI is one command. For pull request 42, STAGE is pr-42, so pnpm test deploys that preview, with its branched database and its preview Worker, and runs the same tests we ran on our machine against it. Set LOCAL too and CI runs it emulated instead.",
1314 }),
1315 term({
1316 group: "ci-run",
1317 tabs: ["GitHub Actions · test"],
1318 title: "pnpm test deploys the preview and tests it",
1319 lines: [
1320 $("pnpm test"),
1321 `${T.ok}${T.bold}▲ deploy${T.reset} ${T.dim}Chat → stage${T.reset} ${T.bold}pr-42${T.reset}`,
1322 ` ${T.ok}+ Files + Messages + Pool${T.reset}`,
1323 ` ${T.ok}+ Db${T.reset} ${T.dim}branch of staging's database${T.reset}`,
1324 ` ${T.ok}+ Chat${T.reset} ${T.dim}preview of staging's Worker${T.reset}`,
1325 ``,
1326 PASSED,
1327 ``,
1328 `${T.ok}1 passed${T.reset}`,
1329 ],
1330 notes:
1331 "In CI it's the same command we ran on our machine. It deploys stage pr-42: the database is a branch of staging's, the Worker is a preview of staging's, and the same test passes against it.",
1332 }),
1333 loop(
1334 "The last step of a pull request is a link to try it",
1335 "Back to the map. That last box in the pull request lane: a comment with a preview link. The agent can read it, and a reviewer can click it and chat in the preview. So how does that comment get there?",
1336 ["comment"],
1337 ),
1338 chat({
1339 snippet: "StackPr.ts",
1340 file: "alchemy.run.ts",
1341 group: "stack",
1342 fontSize: 22,
1343 title: "The Stack comments the preview link on the pull request",
1344 emphasize: [
1345 "GitHub.Comment",
1346 "Config.Int",
1347 "Config.option",
1348 "Config.map",
1349 "if (pullRequest)",
1350 "owner:",
1351 "repository:",
1352 "issueNumber: pullRequest",
1353 "Preview deployed",
1354 "GitHub.providers",
1355 ],
1356 notes:
1357 "A GitHub Comment is a resource too. When the Stack deploys for a PR, it posts the preview URL on it, and updates the same comment on every push.",
1358 }),
1359 {
1360 kind: "comment",
1361 title: "The agent and the reviewer both get a link to try",
1362 pr: { number: 42, title: "Add file uploads to rooms", branch: "agent/uploads" },
1363 checks: [{ name: "test", state: "passed", detail: "stage pr-42" }],
1364 comments: [
1365 {
1366 author: "alchemy",
1367 bot: true,
1368 lines: ["🚀 Preview deployed to https://pr-42-chat.sam.workers.dev"],
1369 },
1370 ],
1371 notes:
1372 "The PR shows green tests from its own copy, and a link to try it. The agent can read the check, and a reviewer can click the link and chat in the preview.",
1373 } satisfies CommentSpec,
1374 inline({
1375 group: "ci",
1376 file: ".github/workflows/pr.yml",
1377 lang: "yaml",
1378 fontSize: 24,
1379 title: "Closing the pull request destroys that copy",
1380 code: PR_YAML_CLOSE,
1381 emphasize: ["closed", "cleanup", "alchemy destroy"],
1382 notes:
1383 "And when the PR is merged or closed, the copy goes away: destroy that stage, and every resource the PR created goes with it.",
1384 }),
1385 term({
1386 group: "ci-run",
1387 tabs: ["GitHub Actions · cleanup"],
1388 title: "alchemy destroy removes everything pr-42 created",
1389 lines: [
1390 $("pnpm alchemy destroy --stage pr-42"),
1391 `${T.red}-${T.reset} ${res("Preview", "GitHub.Comment")} deleted`,
1392 `${T.red}-${T.reset} ${res("Chat", "Cloudflare.Worker")} deleted ${T.dim}preview of staging's Worker${T.reset}`,
1393 `${T.red}-${T.reset} ${res("Pool", "Cloudflare.Hyperdrive")} deleted`,
1394 `${T.red}-${T.reset} ${res("Db", "Neon.Branch")} deleted ${T.dim}branch of staging's database${T.reset}`,
1395 `${T.red}-${T.reset} ${res("Messages", "Cloudflare.Queues.Queue")} deleted`,
1396 `${T.red}-${T.reset} ${res("Files", "Cloudflare.R2.Bucket")} deleted`,
1397 RULE,
1398 `${T.ok}Stack destroyed (6/6)${T.reset}`,
1399 ],
1400 notes:
1401 "The cleanup job is the same destroy we ran by hand, for stage pr-42: the comment, the preview Worker, the database branch and everything else the pull request created. Staging's Worker and database stay untouched, because the PR only referenced them.",
1402 }),
1403 ];
1404
1405 // ── act 6: main → staging → prod ─────────────────────────────────────────
1406 const MAIN_YAML = `on:
1407 push:
1408 branches: [main]
1409
1410 jobs:
1411 release:
1412 runs-on: ubuntu-latest
1413 steps:
1414 - uses: actions/checkout@v5
1415 - run: pnpm install
1416 - run: pnpm test
1417 env: { STAGE: staging }`;
1418 const release: StepSpec[] = [
1419 loop(
1420 "Once it's approved, main takes over",
1421 "The reviewer tried the preview, the checks are green, and the PR is approved. The last lane is main: merge, deploy staging, and run the same tests on it.",
1422 ["merge", "staging", "stagingTest"],
1423 ),
1424 inline({
1425 group: "main",
1426 file: ".github/workflows/main.yml",
1427 lang: "yaml",
1428 fontSize: 30,
1429 title: "Merging to main runs the same tests against staging",
1430 code: MAIN_YAML,
1431 emphasize: ["branches: [main]", "STAGE: staging"],
1432 notes:
1433 "On main, the same command runs with STAGE set to staging. Staging is updated and tested in one step.",
1434 }),
1435 loop("Last box: prod, only when staging is green", "And the last box on the map: prod.", [
1436 "prod",
1437 ]),
1438 inline({
1439 group: "main",
1440 file: ".github/workflows/main.yml",
1441 lang: "yaml",
1442 fontSize: 30,
1443 title: "Only a green staging reaches prod",
1444 code: `${MAIN_YAML}
1445 - run: pnpm alchemy deploy --stage prod`,
1446 emphasize: ["--stage prod"],
1447 notes: "And only if those tests pass does the same program deploy to prod.",
1448 }),
1449 loop(
1450 "One program and one test file, all the way to prod",
1451 "That's the loop. One program describes the whole app. One test file checks it on your machine, emulated or live, on every pull request's copy, and on staging. Every failure along the way is feedback the agent can act on.",
1452 undefined,
1453 [
1454 "edit",
1455 "types",
1456 "local",
1457 "live",
1458 "push",
1459 "pr",
1460 "prTest",
1461 "comment",
1462 "merge",
1463 "staging",
1464 "stagingTest",
1465 "prod",
1466 "feedback",
1467 ],
1468 ),
1469 ];
1470
1471 // ── anywhere: every provider has the same shape ─────────────────────────
1472 const roll = (s: Omit<RollSpec, "kind">): RollSpec => ({ kind: "roll", ...s });
1473
1474 const HOST_TEMPLATE = `export default ⟨0⟩(
1475 "Api",
1476 Effect.gen(function* () {
1477 return { main: import.meta.url⟨1⟩ };
1478 }),
1479 Effect.gen(function* () {
1480 const files = yield* Files;
1481 return {
1482 fetch: Effect.gen(function* () {
1483 const request = yield* HttpServerRequest;
1484 yield* files.upload(request.url, yield* request.text);
1485 return HttpServerResponse.empty({ status: 201 });
1486 }),
1487 };
1488 }).pipe(Effect.provide(⟨2⟩)),
1489 );`;
1490 const HOSTS = ["Workers", "Lambda", "ECS", "Cloud Run", "GKE", "Fly", "Railway", "Hetzner", "Neon"];
1491 const host = (
1492 at: number,
1493 title: string,
1494 values: string[],
1495 check: string,
1496 generated: string,
1497 notes: string,
1498 ) =>
1499 roll({
1500 group: "hosts",
1501 file: "src/Api.ts",
1502 fontSize: 24,
1503 title,
1504 template: HOST_TEMPLATE,
1505 values,
1506 check: `anywhere/${check}`,
1507 beside: { file: "generated at deploy", code: generated },
1508 reel: { items: HOSTS, at },
1509 notes,
1510 });
1511
1512 const JOB_TEMPLATE = `export default ⟨0⟩(
1513 "Report",
1514 Effect.gen(function* () {
1515 return { main: import.meta.url⟨1⟩ };
1516 }),
1517 Effect.gen(function* () {
1518 const files = yield* Files;
1519 return {
1520 run: Effect.gen(function* () {
1521 const report = \`generated at \${new Date().toISOString()}\`;
1522 yield* files.upload("report.txt", report);
1523 }),
1524 };
1525 }).pipe(Effect.provide(⟨2⟩)),
1526 );`;
1527 const JOBS = ["ECS Task", "Cloud Run Job", "Kubernetes Job"];
1528 const job = (
1529 at: number,
1530 title: string,
1531 values: string[],
1532 check: string,
1533 generated: string,
1534 notes: string,
1535 ) =>
1536 roll({
1537 group: "jobs",
1538 file: "src/Report.ts",
1539 fontSize: 24,
1540 title,
1541 template: JOB_TEMPLATE,
1542 values,
1543 check: `anywhere/${check}`,
1544 beside: { file: "generated at deploy", code: generated },
1545 reel: { items: JOBS, at },
1546 notes,
1547 });
1548
1549 const DATABASES = ["Neon", "PlanetScale", "Prisma Postgres", "Cloudflare D1", "AWS Aurora"];
1550
1551 const WEB_TEMPLATE = `export const Web = Effect.gen(function* () {
1552 const api = yield* Api;
1553
1554 return yield* ⟨0⟩.Website.⟨1⟩("Web", {
1555 rootDir: "./apps/web",
1556 env: { API_URL: api.url.as<string>() },
1557 });
1558 });`;
1559 const CLOUDS = ["Cloudflare", "AWS", "Fly", "Hetzner", "Railway", "Prisma", "Neon"];
1560 const FRAMEWORKS = [
1561 "Astro",
1562 "Nextjs",
1563 "Nuxt",
1564 "SvelteKit",
1565 "ReactRouter",
1566 "SolidStart",
1567 "TanStackStart",
1568 "Vite",
1569 "Waku",
1570 "Vocs",
1571 "Octane",
1572 "Foldkit",
1573 ];
1574 const web = (cloud: string, framework: string, title: string, notes: string) =>
1575 roll({
1576 group: "web",
1577 file: "src/Web.ts",
1578 fontSize: 40,
1579 title,
1580 template: WEB_TEMPLATE,
1581 values: [cloud, framework],
1582 check: `anywhere/Web${cloud}${framework === "Astro" ? "" : framework}.ts`,
1583 reel:
1584 framework === "Astro"
1585 ? { items: CLOUDS, at: CLOUDS.indexOf(cloud) }
1586 : { items: FRAMEWORKS, at: FRAMEWORKS.indexOf(framework) },
1587 notes,
1588 });
1589
1590 const OBS_PLATFORMS = ["Axiom", "CloudWatch", "Datadog (someday)"];
1591 const DATADOG_CODE = `export const ObservabilityLive = Layer.unwrap(
1592 Effect.gen(function* () {
1593 const apiKey = yield* Config.Redacted("DD_API_KEY");
1594
1595 // hypothetical: there's no Datadog provider yet
1596 yield* Datadog.Dashboard("Chat", { widgets: [errors] });
1597 yield* Datadog.Monitor("Errors", {
1598 query: "sum(last_5m):errors{service:chat} > 10",
1599 });
1600
1601 return Telemetry.layerOtlp({
1602 url: "https://otlp.datadoghq.com",
1603 headers: { "dd-api-key": apiKey },
1604 });
1605 }),
1606 );`;
1607
1608 const section = (heading: string, subtitle: string, notes: string): StepSpec => ({
1609 kind: "slide",
1610 layout: "section",
1611 title: heading,
1612 heading,
1613 subtitle,
1614 notes,
1615 });
1616
1617 const anywhere: StepSpec[] = [
1618 {
1619 kind: "slide",
1620 layout: "section",
1621 title: "The same loop, on any cloud",
1622 heading: "The same loop, on any cloud",
1623 subtitle: "Every provider has the same shape",
1624 notes:
1625 "Everything so far was Cloudflare, with a detour to AWS. But none of it depended on Cloudflare. Let's flip through what else the same program can reach, from the compute up to the website, and watch how little changes.",
1626 },
1627 chat({
1628 snippet: "../anywhere/Files.ts",
1629 file: "src/Files.ts",
1630 group: "files-anywhere",
1631 fontSize: 21,
1632 title: "Files can have a Layer for each cloud, behind one interface",
1633 quiet: true,
1634 notes:
1635 "Start with Files. Same interface as before, upload a file. Here are three Layers for it: R2, S3 and Google Cloud Storage. Each constructor declares its bucket and the narrowest access its cloud allows.",
1636 }),
1637 section(
1638 "Nine hosts, one API",
1639 "Workers · Lambda · ECS · Cloud Run · GKE · Fly · Railway · Hetzner · Neon",
1640 "First, where the code runs. The same API, with the same request handler, on nine different hosts.",
1641 ),
1642 host(
1643 0,
1644 "The API runs on a Cloudflare Worker…",
1645 ["Cloudflare.Worker", "", "FilesR2"],
1646 "ApiWorker.ts",
1647 `# Worker bindings
1648 r2_buckets:
1649 - binding: Files
1650 bucket_name: chat-dev-sam-files`,
1651 "Here's an API that takes uploads. On a Cloudflare Worker, with the R2 Layer, the bucket is bound straight into the Worker.",
1652 ),
1653 host(
1654 1,
1655 "…on AWS Lambda…",
1656 ["AWS.Lambda.Function", "", "FilesS3"],
1657 "ApiLambda.ts",
1658 `# IAM policy on the Lambda's role
1659 Effect: Allow
1660 Action: s3:PutObject
1661 Resource: arn:aws:s3:::chat-dev-sam-files/*`,
1662 "Change the host to a Lambda function and the Layer to S3. The body doesn't change. The binding now becomes an IAM policy, exactly PutObject on exactly this bucket.",
1663 ),
1664 host(
1665 2,
1666 "…as a container on ECS…",
1667 ["AWS.ECS.Service", ", cluster: yield* Cluster, port: 3000", "FilesS3"],
1668 "ApiEcs.ts",
1669 `# IAM policy on the ECS task role
1670 Effect: Allow
1671 Action: s3:PutObject
1672 Resource: arn:aws:s3:::chat-dev-sam-files/*`,
1673 "Or a long-running container on ECS. Same S3 Layer, and the same policy, now on the task role instead of the Lambda's.",
1674 ),
1675 host(
1676 3,
1677 "…on Cloud Run…",
1678 ["GCP.Run.Service", "", "FilesGCS"],
1679 "ApiRun.ts",
1680 `# IAM binding for the service's account
1681 role: roles/storage.objectUser
1682 resource: chat-dev-sam-files`,
1683 "Google Cloud Run, with Cloud Storage. The binding becomes a Google IAM role on the bucket for the service's account.",
1684 ),
1685 host(
1686 4,
1687 "…on Kubernetes, in Google Cloud…",
1688 ["Kubernetes.Deployment", ", cluster: yield* Gke, port: 3000", "FilesGCS"],
1689 "ApiGke.ts",
1690 `# IAM binding for the Pod's ServiceAccount
1691 role: roles/storage.objectUser
1692 member: principal://…/sa/api
1693 resource: chat-dev-sam-files`,
1694 "Or a Kubernetes Deployment on GKE. Same Layer, but now the role goes to the Pod's ServiceAccount through Workload Identity: no keys, no YAML.",
1695 ),
1696 host(
1697 5,
1698 "…on Fly…",
1699 ["Fly.Service", "", "FilesTigris"],
1700 "ApiFly.ts",
1701 `# Tigris bucket, attached to the Fly app
1702 secrets:
1703 BUCKET_NAME: chat-dev-sam-files
1704 AWS_ENDPOINT_URL_S3: https://fly.storage.tigris.dev
1705 AWS_ACCESS_KEY_ID: tid_…`,
1706 "Fly, with a Tigris bucket. The binding attaches the bucket to the Fly app and sets its credentials as secrets.",
1707 ),
1708 host(
1709 6,
1710 "…on Railway…",
1711 ["Railway.Service", ", project: yield* Chat", "FilesRailway"],
1712 "ApiRailway.ts",
1713 `# Railway service variables
1714 BUCKET_NAME: chat-dev-sam-files
1715 AWS_ENDPOINT_URL: https://…
1716 AWS_ACCESS_KEY_ID: …`,
1717 "Railway, with a Railway bucket. The binding writes the bucket's name and credentials into the service's variables.",
1718 ),
1719 host(
1720 7,
1721 "…on a Hetzner server, with a mounted volume…",
1722 ["Hetzner.Service", ", server: yield* Box, port: 3000", "FilesVolume"],
1723 "ApiHetzner.ts",
1724 `# systemd unit on the Box server
1725 ExecStart: bun /opt/api/main.js
1726
1727 # Volume attached and mounted
1728 Files → /files (ext4, 10 GB)`,
1729 "A box you rent from Hetzner. The API runs as a systemd unit, and Files is a Hetzner Volume mounted at /files, so uploads are just files on disk. Same interface, completely different storage.",
1730 ),
1731 host(
1732 8,
1733 "…or as a Neon Function, and the body never changed",
1734 ["Neon.Function", ", branch: yield* Main", "FilesNeon"],
1735 "ApiNeon.ts",
1736 `# Function environment
1737 AWS_ENDPOINT_URL_S3: https://…neon…
1738 AWS_ACCESS_KEY_ID: … # scoped to Files`,
1739 "Or a Neon Function, with a Neon bucket. Nine hosts. The props change, the Files Layer changes, and the request handler never changed once.",
1740 ),
1741 section(
1742 "Three hosts, one background job",
1743 "ECS Tasks · Cloud Run Jobs · Kubernetes Jobs",
1744 "Not everything serves requests. Jobs run once and exit, and they have the same shape too.",
1745 ),
1746 job(
1747 0,
1748 "Background jobs have the same shape, with run instead of fetch",
1749 ["AWS.ECS.Task", "", "FilesS3"],
1750 "JobEcs.ts",
1751 `# IAM policy on the task role
1752 Effect: Allow
1753 Action: s3:PutObject
1754 Resource: arn:aws:s3:::chat-dev-sam-files/*`,
1755 "Not everything serves requests. A job runs once and exits. Same shape: props, then an Effect that returns run instead of fetch. Here it's an ECS task that writes a report through Files.",
1756 ),
1757 job(
1758 1,
1759 "…as a Cloud Run Job…",
1760 ["GCP.Run.Job", "", "FilesGCS"],
1761 "JobRun.ts",
1762 `# IAM binding for the job's account
1763 role: roles/storage.objectUser
1764 resource: chat-dev-sam-files`,
1765 "The same job on Cloud Run Jobs, with Cloud Storage.",
1766 ),
1767 job(
1768 2,
1769 "…or as a Kubernetes Job",
1770 ["Kubernetes.Job", ", cluster: yield* Gke", "FilesGCS"],
1771 "JobGke.ts",
1772 `# IAM binding for the Job's ServiceAccount
1773 role: roles/storage.objectUser
1774 member: principal://…/sa/report
1775 resource: chat-dev-sam-files`,
1776 "Or a Kubernetes Job on GKE. Services and jobs, on nine hosts, and it's all the same program.",
1777 ),
1778 section(
1779 "Three engines, one durable workflow",
1780 "Cloudflare Workflows · Lambda durable functions · Step Functions",
1781 "Some work takes days and has to survive restarts. Three workflow engines, one way of writing a workflow.",
1782 ),
1783 ...[
1784 {
1785 snippet: "FlowWorkflow.ts",
1786 title: "Durable workflows survive restarts and can sleep for days",
1787 emphasize: ["Cloudflare.Workflow", "Workflows.task", "Workflows.sleep"],
1788 notes:
1789 "Some work takes days: summarize a room tonight, wait a day, save the digest. A durable workflow checkpoints each step, so it survives restarts and can sleep for a day without holding a server. On Cloudflare it's a Workflow: task and sleep, each with a name it replays from.",
1790 },
1791 {
1792 snippet: "FlowDurable.ts",
1793 title: "…on AWS, the same workflow is a Lambda durable function…",
1794 emphasize: [
1795 "AWS.Lambda.DurableFunction",
1796 "Durable.step",
1797 "Durable.sleep",
1798 "{ main: import.meta.url }",
1799 "FilesS3",
1800 ],
1801 notes:
1802 "On AWS it's a Lambda durable function, with almost the same code: step instead of task, and the S3 Files Layer instead of R2. Lambda checkpoints each step and resumes the function after the sleep.",
1803 },
1804 {
1805 snippet: "FlowSfn.ts",
1806 title: "…or a Step Functions state machine, written as an Effect",
1807 emphasize: ["StateMachine.fromProgram", "Sfn.gen", "Sfn.invoke", "Sfn.sleep"],
1808 notes:
1809 "Or Step Functions. Normally that means hand-writing Amazon States Language JSON. Here it's written like an Effect, with Sfn.gen, Sfn.invoke and Sfn.sleep, and compiled to that JSON at deploy, along with the IAM permissions to invoke each Lambda.",
1810 },
1811 ].map((flow, at) =>
1812 chat({
1813 snippet: `../anywhere/${flow.snippet}`,
1814 file: "src/Digest.ts",
1815 group: "flows",
1816 fontSize: 24,
1817 title: flow.title,
1818 emphasize: flow.emphasize,
1819 reel: { items: ["Cloudflare Workflows", "Lambda durable functions", "Step Functions"], at },
1820 notes: flow.notes,
1821 }),
1822 ),
1823 section(
1824 "Five databases, one Layer",
1825 "Neon · PlanetScale · Prisma Postgres · Cloudflare D1 · AWS Aurora",
1826 "Down to the database. Five databases from five companies, all behind the same Database Layer.",
1827 ),
1828 ...[
1829 {
1830 snippet: "DbNeon.ts",
1831 title: "The database can be Neon…",
1832 notes:
1833 "Down to the database. This is the Database Layer from the chat app, on Neon: a project and a branch, fronted by Hyperdrive.",
1834 },
1835 {
1836 snippet: "DbPlanetscale.ts",
1837 title: "…PlanetScale…",
1838 notes:
1839 "Swap in PlanetScale: a Postgres database and a role. Its origin feeds Hyperdrive the same way.",
1840 },
1841 {
1842 snippet: "DbPrisma.ts",
1843 title: "…Prisma Postgres…",
1844 notes: "Or Prisma Postgres. Three different companies, and only the first two lines changed.",
1845 },
1846 {
1847 snippet: "DbD1.ts",
1848 emphasize: ["D1.Database", "D1.QueryDatabase", "SQL.D1Layer"],
1849 title: "…Cloudflare D1, which is SQLite…",
1850 notes:
1851 "It doesn't even have to be Postgres. Cloudflare D1 is SQLite, bound straight into the Worker with no connection pool, and SQL.D1Layer turns it into the same SQL client. History's queries don't change.",
1852 },
1853 {
1854 snippet: "DbAurora.ts",
1855 emphasize: ["RDS.Aurora", "RDS.Connect(", "Effect.map(db"],
1856 title: "…or Aurora on AWS, and nothing above it changes",
1857 notes:
1858 "Or Aurora on AWS, for the Lambda version of the app. RDS.Connect grants read access to the cluster's secret and attaches the function to the database's network, and the Postgres Layer connects with the URL it returns. Five databases, one Layer: History and everything above it still just get a SQL client.",
1859 },
1860 ].map((db, at) =>
1861 chat({
1862 snippet: `../anywhere/${db.snippet}`,
1863 file: "src/Db.ts",
1864 group: "db-anywhere",
1865 fontSize: 22,
1866 title: db.title,
1867 reel: { items: DATABASES, at },
1868 emphasize: "emphasize" in db ? db.emphasize : undefined,
1869 notes: db.notes,
1870 }),
1871 ),
1872 section(
1873 "Events from anywhere",
1874 "GitHub repositories · SQS · Kinesis · DynamoDB Streams",
1875 "Events don't have to come from your own cloud. Anything that can call a webhook can be an event source.",
1876 ),
1877 ...[
1878 {
1879 snippet: "EventsGitHub.ts",
1880 title: "A GitHub repository can be an event source",
1881 emphasize: ["GitHub.consumeRepositoryEvents", "GitHub.RepositoryEventSourceLive"],
1882 generated: `# GitHub webhook on alchemy-run/chat
1883 url: https://chat-dev-sam-archive.workers.dev
1884 /__alchemy/github/alchemy-run/chat
1885 events: [push]
1886 content_type: json
1887 secret: *****
1888
1889 # Worker secret binding, to verify each delivery
1890 WEBHOOK_SECRET=*****`,
1891 notes:
1892 "Events don't have to come from a cloud. A GitHub repository is an event source too. You don't manage a secret: at deploy, the binding generates a random one, creates the webhook on the repository pointed at a path on this Worker, and binds the same secret to the Worker, so it can verify every delivery really came from GitHub. Each event is typed by its name.",
1893 },
1894 {
1895 snippet: "EventsSqs.ts",
1896 emphasize: ["AWS.SQS.Queue", "AWS.SQS.consumeQueueMessages", "QueueEventSource"],
1897 title: "…an SQS queue on AWS…",
1898 generated: `# IAM policy on the Lambda's role
1899 - Effect: Allow
1900 Action:
1901 - sqs:ReceiveMessage
1902 - sqs:DeleteMessage
1903 - sqs:GetQueueAttributes
1904 Resource: arn:aws:sqs:…:chat-dev-sam-messages
1905
1906 # Event source mapping
1907 FunctionName: chat-dev-sam-archive
1908 EventSourceArn: arn:aws:sqs:…:chat-dev-sam-messages
1909 Enabled: true
1910 BatchSize: 10
1911 FunctionResponseTypes: [ReportBatchItemFailures]
1912 MetricsConfig: { Metrics: [EventCount] }`,
1913 notes:
1914 "Back on AWS, event sources all look alike. Consume an SQS queue: the call grants the three consumer permissions and creates the event source mapping that invokes the Lambda.",
1915 },
1916 {
1917 snippet: "EventsKinesis.ts",
1918 emphasize: ["AWS.Kinesis.Stream", "AWS.Kinesis.consumeStreamRecords", "StreamEventSource"],
1919 title: "…a Kinesis stream…",
1920 generated: `# IAM policy on the Lambda's role
1921 - Effect: Allow
1922 Action:
1923 - kinesis:DescribeStream
1924 - kinesis:GetRecords
1925 - kinesis:GetShardIterator
1926 - kinesis:ListShards
1927 Resource: arn:aws:kinesis:…:stream/chat-dev-sam-messages
1928
1929 # Event source mapping
1930 FunctionName: chat-dev-sam-archive
1931 EventSourceArn: arn:aws:kinesis:…:stream/chat-dev-sam-messages
1932 Enabled: true
1933 StartingPosition: LATEST
1934 BatchSize: 100
1935 FunctionResponseTypes: [ReportBatchItemFailures]
1936 MetricsConfig: { Metrics: [EventCount] }`,
1937 notes:
1938 "A Kinesis stream: swap the resource and the consume call. The permissions and the mapping change to match, the handler doesn't.",
1939 },
1940 {
1941 snippet: "EventsDynamo.ts",
1942 emphasize: ["AWS.DynamoDB.Table", "AWS.DynamoDB.consumeTableChanges", "TableEventSource"],
1943 title: "…or every change to a DynamoDB table",
1944 generated: `# Table: stream turned on
1945 TableName: chat-dev-sam-messages
1946 StreamSpecification:
1947 StreamEnabled: true
1948 StreamViewType: NEW_IMAGE
1949
1950 # IAM policy on the Lambda's role
1951 - Effect: Allow
1952 Action:
1953 - dynamodb:DescribeStream
1954 - dynamodb:GetRecords
1955 - dynamodb:GetShardIterator
1956 Resource: arn:aws:dynamodb:…:table/chat-dev-sam-messages/stream/…
1957 - Effect: Allow
1958 Action: [dynamodb:ListStreams]
1959 Resource: arn:aws:dynamodb:…:table/chat-dev-sam-messages
1960
1961 # Event source mapping
1962 FunctionName: chat-dev-sam-archive
1963 EventSourceArn: arn:aws:dynamodb:…:table/chat-dev-sam-messages/stream/…
1964 Enabled: true
1965 StartingPosition: LATEST
1966 BatchSize: 100
1967 FunctionResponseTypes: [ReportBatchItemFailures]
1968 MetricsConfig: { Metrics: [EventCount] }`,
1969 notes:
1970 "Or every change to a DynamoDB table. This one also changes the table itself: it turns on the table's stream with the view type you asked for, then grants the stream permissions and creates the mapping on the stream's ARN. Four event sources, one shape.",
1971 },
1972 ].map((ev, at) =>
1973 chat({
1974 snippet: `../anywhere/${ev.snippet}`,
1975 file: "src/Archive.ts",
1976 group: "events",
1977 fontSize: 20,
1978 title: ev.title,
1979 emphasize: ev.emphasize,
1980 beside: { file: "generated at deploy", lang: "yaml", src: { code: ev.generated } },
1981 reel: { items: ["GitHub", "SQS", "Kinesis", "DynamoDB Streams"], at },
1982 notes: ev.notes,
1983 }),
1984 ),
1985 section(
1986 "Seven clouds, one Website",
1987 "Cloudflare · AWS · Fly · Hetzner · Railway · Prisma · Neon",
1988 "At the top of the pyramid, the website. We made every Website variant take the same props, so where your site runs is one word, and so is the framework.",
1989 ),
1990 web(
1991 "Cloudflare",
1992 "Astro",
1993 "At the top, the chat's website deploys to Cloudflare…",
1994 "Finally the top of the pyramid: the website. One call deploys an Astro site to Cloudflare, with the API's URL passed in.",
1995 ),
1996 web("AWS", "Astro", "…AWS…", "Change the namespace and the same site deploys to AWS."),
1997 web("Fly", "Astro", "…Fly…", "To Fly."),
1998 web("Hetzner", "Astro", "…a Hetzner server…", "To a Hetzner box."),
1999 web("Railway", "Astro", "…Railway…", "To Railway."),
2000 web("Prisma", "Astro", "…Prisma…", "To Prisma."),
2001 web(
2002 "Neon",
2003 "Astro",
2004 "…or Neon, with the same props every time",
2005 "Or Neon. Seven clouds, the same props every time.",
2006 ),
2007 web(
2008 "Neon",
2009 "Nextjs",
2010 "The framework is one word too",
2011 "And the framework is one word too: Next.js…",
2012 ),
2013 web("Neon", "Nuxt", "The framework is one word too", "…Nuxt…"),
2014 web("Neon", "SvelteKit", "The framework is one word too", "…SvelteKit…"),
2015 web("Neon", "ReactRouter", "…and the rest", "…React Router…"),
2016 web("Neon", "SolidStart", "…and the rest", "…SolidStart…"),
2017 web("Neon", "TanStackStart", "…and the rest", "…TanStack Start…"),
2018 web("Neon", "Vite", "…and the rest", "…Vite…"),
2019 web("Neon", "Waku", "…and the rest", "…Waku…"),
2020 web("Neon", "Vocs", "…and the rest", "…Vocs…"),
2021 web("Neon", "Octane", "…and the rest", "…Octane…"),
2022 web(
2023 "Neon",
2024 "Foldkit",
2025 "…and the rest",
2026 "…and Foldkit. Twelve frameworks, same props, and on every cloud alchemy dev runs the framework's own dev server.",
2027 ),
2028 section(
2029 "Three platforms, one observability Layer",
2030 "Axiom · CloudWatch · Datadog (someday)",
2031 "Last, the column beside the pyramid. Observability is a Layer like the rest, so the platform behind it is a choice.",
2032 ),
2033 ...[
2034 {
2035 snippet: "Observability.ts",
2036 title: "Observability is a Layer, so the platform is one swap away",
2037 notes:
2038 "Last, the pillar beside the pyramid. Observability is a Layer like the rest, so the platform behind it is a choice. Here's the Axiom version: datasets, a token, a dashboard, a monitor, and the exporter.",
2039 },
2040 {
2041 snippet: "../anywhere/ObservabilityCloudWatch.ts",
2042 title: "…CloudWatch plots and alarms on what Lambda already collects…",
2043 notes:
2044 "For the Lambda version of the API, it's CloudWatch. Lambda already ships logs and metrics there, so this Layer only declares a CloudWatch dashboard and an alarm on the function's errors.",
2045 },
2046 ].map((step, at) =>
2047 chat({
2048 snippet: step.snippet,
2049 file: "src/Observability.ts",
2050 group: "observability-swap",
2051 fontSize: 20,
2052 title: step.title,
2053 reel: { items: OBS_PLATFORMS, at },
2054 notes: step.notes,
2055 }),
2056 ),
2057 inline({
2058 group: "observability-swap",
2059 file: "src/Observability.ts",
2060 fontSize: 20,
2061 title: "…and a Datadog Layer would have exactly the same shape",
2062 code: DATADOG_CODE,
2063 emphasize: ["Datadog.Dashboard", "Datadog.Monitor", "Telemetry.layerOtlp"],
2064 reel: { items: OBS_PLATFORMS, at: 2 },
2065 notes:
2066 "Datadog isn't an Alchemy provider yet, so this one is hypothetical. But it would be the same shape: a dashboard and a monitor in the constructor, and an exporter at the end. The exporter part is real today: Telemetry.layerOtlp sends to any OpenTelemetry backend.",
2067 }),
2068 chat({
2069 snippet: "ObservabilityTwo.ts",
2070 file: "src/Observability.ts",
2071 group: "observability-two",
2072 fontSize: 24,
2073 title: "Layers compose, so telemetry can go to two places at once",
2074 emphasize: ["Telemetry.layerOtlp", "Layer.mergeAll(Axiom, Honeycomb)"],
2075 notes:
2076 "And because they're Layers, they compose. Merge Axiom with a Honeycomb exporter and every span goes to both, with the same trace ids. That's how you migrate between platforms without a gap.",
2077 }),
2078 loop(
2079 "Whatever you pick, it's the same loop",
2080 "And whichever of these you pick, it's the same program, the same test file, and the same loop from edit to production.",
2081 undefined,
2082 [
2083 "edit",
2084 "types",
2085 "local",
2086 "live",
2087 "push",
2088 "pr",
2089 "prTest",
2090 "comment",
2091 "merge",
2092 "staging",
2093 "stagingTest",
2094 "prod",
2095 "feedback",
2096 ],
2097 ),
2098 ];
2099
2100 export const steps: StepSpec[] = [
2101 ...opening,
2102 ...theStack,
2103 ...twoPrograms,
2104 ...modules,
2105 ...compose,
2106 ...program,
2107 ...theLoop,
2108 ...tests,
2109 ...ci,
2110 ...shared,
2111 ...release,
2112 ...anywhere,
2113 ];