Projects · platform architecture

An architecture that fails the build: architect-os, traced through its source

Most agent platforms are described by a diagram and held together by review. This one is small enough to read in an afternoon and strict enough that a wrong import fails the build: the architecture is enforced, not just described.1 A client calls one intent tool on a single gateway; the service that owns the tool runs an agent in a sandbox and answers with a validated result.2 It is a skeleton, and it says where it stops.35

Runsfour tiers behind one exposed port: a proxy, a gateway, one service per domain, one data component3
Exposes2 intent tools, recall and remember, on a single MCP server6
Isolatesone short-lived container per call; the agent inside has no built-in tool2325
Answersa Result validated against the tool's schema, with a named error code on failure2930
Enforces12 dependency rules, run with the tests and in CI, each proved by a file that breaks it1420
Size43 modules and 1,963 lines of TypeScript outside tests, after behaviour moved into descriptive files34
Statusa skeleton: version 0.1.0, nothing released, the live agent path not covered by the default suite383935
architect-os in 90 seconds. Silent. Generated from cdeust/architect-os at f699c89 (); every figure it prints is read from site-facts.json.
What the film says, scene by scene
  1. A layered architecture holds only while something enforces it. In architect-os the architecture is enforced, not just described: a wrong import fails the build.
  2. Four tiers, one path for a call. A client calls one intent tool; the gateway routes it to the owning service. Proxy: the only exposed component. Gateway: auth, catalogue, routing, quotas, audit. Service: runs a sandboxed Claude Agent SDK worker. Data: the only component that imports pg.
  3. Each component: four layers, one composition root. domain: entities and ports. application: use cases, constructor-injected ports. infrastructure: adapters, with an in-memory adapter for every port. presentation: MCP or HTTP translation only. src/main.ts: the only place that builds objects.
  4. Hard boundaries, checked by npm run arch. pg: only in data/src/infrastructure. Claude Agent SDK: only in services/*/worker. MCP SDK: only in presentation and infrastructure. Import cycles: none.
  5. Failures are values. A tool call returns a Result with status failed and a named error code; nothing throws across a service boundary.
  6. Every brick arrives with its tests. Unit tests for each layer it touches. A contract test for each port, run against every adapter, the in-memory one included. An end-to-end case when it is on the path of a call.
  7. What it does not do yet. An architecture skeleton, with no release. The live agent SDK path is not exercised in the default suite. Docker images and docker compose up are not exercised by CI.
  8. architect-os. Package agentic-ai 0.1.0, MIT. Two intent tools: recall and remember. $ npm ci $ npm run check

Sources: Sources: CLAUDE.md, README, docs/testing.md and CHANGELOG of cdeust/architect-os at commit f699c89. No release exists; the film describes the skeleton on main.

Exhibit 01 · the shape

One entry point, four tiers, one typed way to the data

A client sees one MCP server and two tools. Behind that server are four tiers, and each talks only to its neighbour: a proxy that is the only exposed component, a gateway, one service per domain, and one data component.34 The gateway authenticates the caller, applies a quota, routes the call to the service that owns the tool and journals it. It runs no agent and touches no data, and it forwards the service's answer without interpreting it.5

The tools are intent tools: recall and remember, not search and insert.6 The low-level tools exist, but only an agent inside a worker can call them, and each is declared once as a view of one data operation.7 Handing the low-level tools to clients was considered and rejected: it moves cost, limits and validation to every client and leaves no single place to validate the output.8 The database sits behind the same kind of narrowing: one component imports the driver, and it exposes named, typed operations, never free-form SQL.10

CLIENT Any MCP host it sees one server and two tools PROXY The only exposed component /mcp · /healthz no logic GATEWAY One MCP server auth, quota, routing, audit it runs no agent and touches no data SERVICES/MEMORY Two intent tools recall · remember it validates the input, then the worker's output WORKER One container per call a Claude Agent SDK agent with the service's internal tools and no other THE ONLY SHARED CODE packages/contracts Result, Run, RunEvent and the schemas of every tool and data operation. Schemas and types, no logic. Components call each other over the network. DATA Typed operations the only importer of pg; never free-form SQL POSTGRES + PGVECTOR runs and their events memory vectors FOUR NETWORK ZONES public: the proxy, the only published port · app: proxy, gateway, memory, data · exec: memory and its workers · data: data and postgres
Four network zones, one published port. Only the proxy is on the public zone; the three inner zones are internal. A worker reaches the memory service's internal tools and the secrets broker and nothing else, and neither a worker nor the gateway has a route to the database.11 A test checks these memberships against the compose file.12 The components share no code except one package of schemas, which holds no logic.9
Exhibit 02 · the guard

The layering is a rule set, and a test proves the rules bite

The layering inside a component is the usual one: domain, application, infrastructure, presentation, and one composition root that is the only place objects are built.13 What is less usual is that none of it rests on review. Twelve named rules in one configuration file are run by the same command as the tests, and CI runs that command.141516

Three of the rules confine a dependency to one place: the database driver to the data component's infrastructure, the Claude Agent SDK to a worker, the MCP SDK to presentation and infrastructure.171819 A guard that has never been seen to fail proves little. So a test writes one violating file per rule under the real component directories, checks that each rule fires on its file, deletes the files and checks that the tree is green again.20 The decision record gives the reason in one line: reviewers miss imports, CI does not.22

INSIDE ONE COMPONENT presentation MCP or HTTP only application use cases domain entities and ports infrastructure adapters src/main.ts the one place objects are built; nothing imports it TWELVE RULES, ONE COMMAND npm run arch each layer imports only what it may no import between components the database driver only in the data component the agent SDK only in a worker the MCP SDK only at the edges a worker image holds no service source the shared package imports no component no import cycle anywhere THE PROOF A test breaks every rule it writes one violating file per rule, under the real component directories, checks that each rule fires on its file, deletes the files, and checks the tree is green again test/arch/guard.test.ts WHERE IT RUNS One command runs the type check, the formatter, the tests and the guard; CI runs that command on every pull request.
Twelve rules, thirteen files that break them. Every rule has at least one fixture and the cycle rule has two.21 The same idea is applied to behaviour: what a descriptive file can express, a SQL statement, a prompt, a table of operations, is not written in code, and each such file has a test that loads it and rejects a broken copy.33
Exhibit 03 · the worker

An agent with no tools of its own, and an answer that is checked

Each call gets its own container: a read-only filesystem, every capability dropped, a non-root user, memory and process limits, one internal network.2324 Inside it, the agent has no built-in tool. Its tool list is empty, the allowed tools are the service's internal ones, no settings file is loaded and no session is kept.25 These options stay in code on purpose: the documentation calls them the security floor, as opposed to behaviour, which lives in files.26

The worker does not decide whether its own output can be trusted. The service parses what the worker printed and validates it against the tool's schema; a misfit is recorded as a failure with a named code, because a prompt-injected agent could otherwise return anything.2728 Failures are values: every tool answers with a Result, and its error code comes from a closed list.2930 Each step of a call is recorded as an event of its run.31 A completed run cannot be completed again, and that rule is held by a database trigger, not by TypeScript.32

1 · THE SERVICE Validates the input a bad input is answered INVALID_INPUT and no run is created 2 · THE RUN Creates a run every step is an event run.created worker.started worker.exited output.validated run.completed 3 · ONE CONTAINER PER CALL --read-only --cap-drop ALL --user 10001:10001 --memory --pids-limit --network THE AGENT INSIDE tools: [] settingSources: [] only the service's internal tools turn and cost limits set by the service 4 · THE SERVICE AGAIN Validates the output what the worker printed is parsed, then checked against the tool's schema a misfit is recorded as a failure: WORKER_OUTPUT_INVALID the worker does not decide trust NOT COVERED BY THE DEFAULT SUITE the live SDK path, which needs the secrets broker and a key the SQL files against a real database, unless one is set the Docker images and the compose stack IN THE DATABASE a completed run cannot be completed again: a trigger refuses the update 0003_runs_immutable.sql THE ANSWER Result { status, data, evidence, run_id, cost, error? } a failure is a value with a named code
What the default suite does not cover. The path through the live SDK is not exercised, because it needs the secrets broker and a key, and the broker is not part of the skeleton.3536 The local container adapter needs the Docker socket; a production adapter behind the same port is stated as the way out, not built.37 The SQL files meet a real database only when one is configured, and the Docker images are not exercised by CI.35
1README.md:20:20 — “The architecture is enforced, not just described: npm run arch fails on a wrong layer import, a cross-component import, pg outside data/src/infrastructure, the agent SDK outside a worker, the MCP SDK outside presentation/infrastructure, or a cycle.”
2README.md:3:3 — “Clients call one intent tool on a single gateway; the owning service runs a sandboxed Claude Agent SDK worker and answers with a validated Result. Data access lives in one typed component.”
3docs/architecture.md:3:3 — “Four tiers. Each tier has one job and talks only to its neighbour.”
4docs/architecture.md:16:16 — “The only exposed component. Forwards /mcp to the gateway and answers /healthz. TLS terminates here in production. No logic.”
5docs/architecture.md:17:17 — the gateway lists the catalogue, authenticates, applies the quota, routes and journals: “It runs no agent and touches no data. It forwards the service answer without interpreting it.”
6packages/contracts/src/tools.ts:56:56 — TOOLS declares two intent tools, recall and remember, each with its owner (memory), its input schema and its data schema.
7packages/contracts/src/data-ops.ts:57:57 — INTERNAL_TOOLS declares memory_search as a view of the data operation memory.search and memory_insert as a view of memory.insert.
8docs/design.md:16:16 — decision 3, rejected alternative: “expose low-level tools (search, insert) to clients and let the client agent compose them. It moves cost, limits and validation to every client and gives no single place to validate output.”
9docs/architecture.md:21:21 — “packages/contracts is the only shared package … It holds no logic.”
10docs/architecture.md:19:19 — “The only component that imports pg. It exposes typed operations … over an internal HTTP API, never free-form SQL.”
11docs/architecture.md:46:46 — the zone table: public holds the proxy, “The only zone with a published port”; in exec, “Workers reach memory's internal tools and the secrets broker, nothing else”; in data, “Workers and the gateway cannot reach the database.”
12docs/architecture.md:49:49 — “test/infra/compose.test.ts checks these memberships against compose.yaml.”
13docs/architecture.md:29:29 — the layer diagram, with src/main.ts as “the composition root, the only place objects are built”.
14.dependency-cruiser.cjs:13:13 — the first of twelve named rules; the others follow in the same file, down to mcp-sdk-only-in-presentation-and-infrastructure.
15package.json:24:24 — npm run check chains the type check, the format check, the tests and npm run arch.
16.github/workflows/ci.yml:30:30 — the CI job runs npm run check.
17.dependency-cruiser.cjs:80:80 — “Only data/src/infrastructure may import pg. No database access outside data.”
18.dependency-cruiser.cjs:87:87 — “The Claude Agent SDK runs only inside a worker image: services/<name>/worker.”
19.dependency-cruiser.cjs:94:94 — the rule that confines @modelcontextprotocol/sdk to the presentation and infrastructure layers of the gateway and the services.
20test/arch/guard.test.ts:116:116 — the test “catches every kind of violation on temporary fixtures, then is green again once they are removed”.
21test/arch/guard.test.ts:41:41 — the first of thirteen fixtures; every one of the twelve rules has at least one, and the cycle rule has two.
22docs/design.md:55:55 — decision 10: “Rejected: documentation and review only. Reviewers miss imports; CI does not.”
23docs/design.md:23:23 — decision 4: “one container per execution; read-only filesystem, no capabilities, non-root, memory/pids/time limits, exec network only.”
24services/memory/src/infrastructure/docker-runner.ts:47:47 — the Docker arguments start here: --read-only, a noexec tmpfs, --cap-drop ALL, no-new-privileges, --user 10001:10001, --network, --memory, --pids-limit.
25services/memory/worker/sdk-agent.ts:51:51 — the agent options: strictMcpConfig: true, tools: [], allowedTools built from the internal tool names, permissionMode: 'dontAsk', settingSources: [], persistSession: false, then maxTurns and maxBudgetUsd from the request.
26docs/agents.md:18:18 — “None … These stay in code: they are the security floor, not behaviour.”
27docs/agents.md:21:21 — “The worker does not decide trust. The service parses stdout with WorkerOutputSchema then validates data with the tool schema; a violation is WORKER_OUTPUT_INVALID and the run is recorded as failed.”
28docs/design.md:45:45 — decision 8, rejected alternatives: throwing across the service boundary, “the client cannot tell a bad input from a crashed worker”, and trusting the worker output, “a prompt-injected agent could return anything”.
29docs/architecture.md:71:71 — the Result type: a status, the data, the evidence, the run id, the cost, and an error when the status is not ok.
30packages/contracts/src/result.ts:8:8 — the closed list of error codes, from INVALID_INPUT to WORKER_OUTPUT_INVALID.
31docs/architecture.md:60:60 — steps 1 to 6 of the call list the events of a run: run.created, worker.started, worker.exited, output.validated or output.invalid, run.completed.
32data/migrations/0003_runs_immutable.sql:1:1 — “a completed run is immutable. Completing it again raises 55000 … which sql/operations.json maps to INVALID_OPERATION.”
33docs/design.md:66:66 — decision 12: “a behaviour that a descriptive file can express is not written in code. Code is reserved for protocol translation (MCP, HTTP), process and container control, validation against a schema, security floors, and one generic loader or executor per kind of file.”
34docs/design.md:70:70 — “46 modules and 2209 lines at the skeleton commit, 43 modules and 1963 lines after (-11 %). Part of the difference is SQL text that moved out of TypeScript strings into data/sql/.”
35docs/testing.md:54:54 — the three gaps listed under this heading: the live SDK path “needs the broker and an API key”; the SQL files meet a real database “only when TEST_DATABASE_URL is set”; “Docker images and docker compose up are not exercised by CI”.
36README.md:44:44 — “Workers need the secrets broker to reach Anthropic; it is not part of this skeleton”.
37docs/design.md:25:25 — “Known limit: the local Docker adapter needs the Docker socket. Production should use an orchestrator adapter (job API with a restricted service account) behind the same port.”
38package.json:3:3 — package agentic-ai, version 0.1.0.
39CHANGELOG.md:13:13 — under the only heading, Unreleased: “The repository was replaced by the architecture skeleton. The previous content is archived under the tag archive/v1-2026-10-29 and is no longer maintained.”