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
What the film says, scene by scene
- 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.
- 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.
- 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.
- 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.
- Failures are values. A tool call returns a Result with status failed and a named error code; nothing throws across a service boundary.
- 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.
- 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.
- 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.
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
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
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