Projets · architecture de plateforme

Une architecture qui fait échouer le build : architect-os, suivi dans son code

La plupart des plateformes d’agents sont décrites par un schéma et tenues par la relecture. Celle-ci est assez petite pour être lue en une après-midi et assez stricte pour qu’un import interdit fasse échouer le build : l’architecture est imposée, pas seulement décrite.1 Un client appelle un outil d’intention sur une passerelle unique ; le service propriétaire de l’outil lance un agent dans un bac à sable et répond par un résultat validé.2 C’est un squelette, et il dit où il s’arrête.35

Tournequatre niveaux derrière un seul port exposé : un proxy, une passerelle, un service par domaine, un composant de données3
Expose2 outils d’intention, recall et remember, sur un seul serveur MCP6
Isoleun conteneur éphémère par appel ; l’agent à l’intérieur n’a aucun outil intégré2325
Répondun Result validé contre le schéma de l’outil, avec un code d’erreur nommé en cas d’échec2930
Impose12 règles de dépendance, exécutées avec les tests et en CI, chacune prouvée par un fichier qui la viole1420
Taille43 modules et 1 963 lignes de TypeScript hors tests, après le passage des comportements dans des fichiers descriptifs34
Étatun squelette : version 0.1.0, rien de publié, le chemin d’agent réel non couvert par la suite par défaut383935
architect-os en 90 secondes. Vidéo muette. Générée à partir de cdeust/architect-os à f699c89 () ; chaque chiffre affiché est lu dans site-facts.json.
Le texte du film, scène par scène
  1. Une architecture en couches ne tient que si quelque chose l’impose. Dans architect-os, l’architecture est imposée, pas seulement décrite : un mauvais import fait échouer le build.
  2. Quatre niveaux, un seul chemin pour un appel. Un client appelle un outil d’intention ; la passerelle le route vers le service qui le possède. Proxy: le seul composant exposé. Passerelle: authentification, catalogue, routage, quotas, audit. Service: lance un worker Claude Agent SDK isolé. Données: le seul composant qui importe pg.
  3. Chaque composant : quatre couches, une racine de composition. domain: entités et ports. application: cas d’usage, ports injectés par constructeur. infrastructure: adaptateurs, dont un en mémoire pour chaque port. presentation: traduction MCP ou HTTP, rien d’autre. src/main.ts: le seul endroit qui construit des objets.
  4. Des frontières strictes, contrôlées par npm run arch. pg: seulement dans data/src/infrastructure. Claude Agent SDK: seulement dans services/*/worker. SDK MCP: seulement en presentation et infrastructure. Cycles d’import: aucun.
  5. Les échecs sont des valeurs. Un appel d’outil renvoie un Result de statut failed avec un code d’erreur nommé ; rien ne lève d’exception à travers une frontière de service.
  6. Chaque brique arrive avec ses tests. Des tests unitaires pour chaque couche touchée. Un test de contrat par port, lancé sur chaque adaptateur, y compris celui en mémoire. Un cas de bout en bout quand elle est sur le chemin d’un appel.
  7. Ce qu’il ne fait pas encore. Un squelette d’architecture, sans release. Le chemin réel du SDK d’agent n’est pas exercé par la suite par défaut. Les images Docker et docker compose up ne sont pas exercés par la CI.
  8. architect-os. Paquet agentic-ai 0.1.0, MIT. Deux outils d’intention : recall et remember. $ npm ci $ npm run check

Sources: Sources : CLAUDE.md, README, docs/testing.md et CHANGELOG de cdeust/architect-os au commit f699c89. Aucune release n’existe ; le film décrit le squelette sur main.

Pièce 01 · la forme

Un point d’entrée, quatre niveaux, un seul chemin typé vers les données

Un client voit un serveur MCP et deux outils. Derrière ce serveur, quatre niveaux, dont chacun ne parle qu’à son voisin : un proxy qui est le seul composant exposé, une passerelle, un service par domaine et un composant de données.34 La passerelle authentifie l’appelant, applique un quota, route l’appel vers le service propriétaire de l’outil et le journalise. Elle ne lance aucun agent et ne touche à aucune donnée, et elle transmet la réponse du service sans l’interpréter.5

Les outils sont des outils d’intention : recall et remember, pas « chercher » et « insérer ».6 Les outils de bas niveau existent, mais seul un agent dans un worker peut les appeler, et chacun est déclaré une fois comme une vue d’une opération de données.7 Donner les outils de bas niveau aux clients a été envisagé puis rejeté : cela reporte le coût, les limites et la validation sur chaque client et ne laisse aucun endroit unique où valider la sortie.8 La base de données est derrière le même resserrement : un seul composant importe le pilote, et il expose des opérations nommées et typées, jamais de SQL libre.10

CLIENT Tout hôte MCP il voit un serveur et deux outils PROXY Le seul composant exposé /mcp · /healthz aucune logique PASSERELLE Un serveur MCP auth, quota, routage, audit elle ne lance aucun agent et ne touche aucune donnée SERVICES/MEMORY Deux outils d’intention recall · remember il valide l’entrée, puis la sortie du worker WORKER Un conteneur par appel un agent Claude Agent SDK avec les outils internes du service, rien d’autre LE SEUL CODE PARTAGÉ packages/contracts Result, Run, RunEvent et les schémas de chaque outil et opération de données. Des schémas et des types, aucune logique. Les composants s’appellent par le réseau. DONNÉES Opérations typées seul importateur de pg ; jamais de SQL libre POSTGRES + PGVECTOR les runs et leurs événements les vecteurs de mémoire QUATRE ZONES RÉSEAU public : le proxy, seul port publié · app : proxy, passerelle, mémoire, données · exec : mémoire et ses workers · data : données et postgres
Quatre zones réseau, un seul port publié. Seul le proxy est dans la zone publique ; les trois zones intérieures sont internes. Un worker atteint les outils internes du service mémoire et le courtier de secrets, rien d’autre, et ni un worker ni la passerelle n’ont de route vers la base de données.11 Un test vérifie ces appartenances contre le fichier compose.12 Les composants ne partagent aucun code, sauf un paquet de schémas qui ne contient aucune logique.9
Pièce 02 · le garde

Le découpage en couches est un jeu de règles, et un test prouve qu’elles mordent

Le découpage à l’intérieur d’un composant est classique : domaine, application, infrastructure, présentation, et une racine de composition qui est le seul endroit où les objets sont construits.13 Ce qui l’est moins, c’est que rien ne repose sur la relecture. Douze règles nommées, dans un seul fichier de configuration, sont exécutées par la même commande que les tests, et la CI exécute cette commande.141516

Trois de ces règles confinent une dépendance à un seul endroit : le pilote de base de données à l’infrastructure du composant de données, le Claude Agent SDK à un worker, le SDK MCP à la présentation et à l’infrastructure.171819 Un garde qu’on n’a jamais vu échouer ne prouve pas grand-chose. Un test écrit donc un fichier fautif par règle dans les vrais répertoires des composants, vérifie que chaque règle se déclenche sur son fichier, supprime les fichiers et vérifie que l’arbre est de nouveau vert.20 Le registre des décisions en donne la raison en une ligne : les relecteurs laissent passer des imports, la CI non.22

DANS UN COMPOSANT présentation MCP ou HTTP application cas d’usage domaine entités et ports infrastructure adaptateurs src/main.ts le seul endroit où naissent les objets ; rien ne l’importe DOUZE RÈGLES, UNE COMMANDE npm run arch chaque couche n’importe que ce qu’elle peut aucun import entre composants le pilote de base, seulement dans les données le SDK d’agent seulement dans un worker le SDK MCP seulement aux bords une image de worker sans source du service le paquet partagé n’importe aucun composant aucun cycle d’import, nulle part LA PREUVE Un test viole chaque règle il écrit un fichier fautif par règle, dans les vrais répertoires des composants, vérifie que chaque règle se déclenche, supprime les fichiers, et vérifie que l’arbre est de nouveau vert test/arch/guard.test.ts OÙ ELLE S’EXÉCUTE Une commande lance la vérification des types, le formatage, les tests et le garde ; la CI l’exécute à chaque pull request.
Douze règles, treize fichiers qui les violent. Chaque règle a au moins une fixture et la règle des cycles en a deux.21 La même idée s’applique au comportement : ce qu’un fichier descriptif peut exprimer, une requête SQL, un prompt, une table d’opérations, n’est pas écrit en code, et chacun de ces fichiers a un test qui le charge et rejette une copie cassée.33
Pièce 03 · le worker

Un agent sans outils propres, et une réponse qui est vérifiée

Chaque appel a son propre conteneur : système de fichiers en lecture seule, toutes les capacités retirées, utilisateur non root, limites de mémoire et de processus, un seul réseau interne.2324 À l’intérieur, l’agent n’a aucun outil intégré. Sa liste d’outils est vide, les outils autorisés sont ceux, internes, du service, aucun fichier de réglages n’est chargé et aucune session n’est conservée.25 Ces options restent dans le code à dessein : la documentation les appelle le plancher de sécurité, par opposition au comportement, qui vit dans des fichiers.26

Le worker ne décide pas si sa propre sortie est digne de confiance. Le service analyse ce que le worker a écrit et le valide contre le schéma de l’outil ; un écart est enregistré comme un échec avec un code nommé, parce qu’un agent victime d’une injection de prompt pourrait sinon renvoyer n’importe quoi.2728 Les échecs sont des valeurs : chaque outil répond par un Result, dont le code d’erreur vient d’une liste fermée.2930 Chaque étape d’un appel est enregistrée comme un événement de son run.31 Un run terminé ne peut pas être terminé une seconde fois, et cette règle est tenue par un déclencheur de base de données, pas par du TypeScript.32

1 · LE SERVICE Valide l’entrée une entrée invalide reçoit INVALID_INPUT et aucun run n’est créé 2 · LE RUN Crée un run chaque étape, un événement run.created worker.started worker.exited output.validated run.completed 3 · UN CONTENEUR PAR APPEL --read-only --cap-drop ALL --user 10001:10001 --memory --pids-limit --network L’AGENT À L’INTÉRIEUR tools: [] settingSources: [] seulement les outils internes du service tours et coût limités par le service 4 · LE SERVICE, DE NOUVEAU Valide la sortie ce que le worker a écrit est analysé, puis vérifié contre le schéma de l’outil un écart est enregistré comme un échec : WORKER_OUTPUT_INVALID le worker ne décide pas de la confiance NON COUVERT PAR LA SUITE PAR DÉFAUT le chemin SDK réel : il faut le courtier de secrets et une clé les fichiers SQL contre une vraie base, sauf si configurée les images Docker et la pile compose DANS LA BASE DE DONNÉES un run terminé ne peut pas être terminé à nouveau : un déclencheur le refuse 0003_runs_immutable.sql LA RÉPONSE Result { status, data, evidence, run_id, cost, error? } un échec est une valeur avec un code nommé
Ce que la suite par défaut ne couvre pas. Le chemin par le SDK réel n’est pas exercé, parce qu’il lui faut le courtier de secrets et une clé, et que le courtier ne fait pas partie du squelette.3536 L’adaptateur de conteneur local a besoin du socket Docker ; un adaptateur de production derrière le même port est indiqué comme la sortie, pas construit.37 Les fichiers SQL ne rencontrent une vraie base que si une base est configurée, et les images Docker ne sont pas exercées par la 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 — la passerelle liste le catalogue, authentifie, applique le quota, route et journalise : « It runs no agent and touches no data. It forwards the service answer without interpreting it. »
6packages/contracts/src/tools.ts:56 :56 — TOOLS déclare deux outils d’intention, recall et remember, chacun avec son propriétaire (memory), son schéma d’entrée et son schéma de données.
7packages/contracts/src/data-ops.ts:57 :57 — INTERNAL_TOOLS déclare memory_search comme une vue de l’opération de données memory.search et memory_insert comme une vue de memory.insert.
8docs/design.md:16 :16 — décision 3, alternative rejetée : « 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 — le tableau des zones : public contient le proxy, « The only zone with a published port » ; dans exec, « Workers reach memory's internal tools and the secrets broker, nothing else » ; dans 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 — le schéma des couches, avec src/main.ts comme « the composition root, the only place objects are built ».
14.dependency-cruiser.cjs:13 :13 — la première de douze règles nommées ; les autres suivent dans le même fichier, jusqu’à mcp-sdk-only-in-presentation-and-infrastructure.
15package.json:24 :24 — npm run check enchaîne la vérification des types, celle du formatage, les tests et npm run arch.
16.github/workflows/ci.yml:30 :30 — le job de CI exécute 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 — la règle qui confine @modelcontextprotocol/sdk aux couches présentation et infrastructure de la passerelle et des services.
20test/arch/guard.test.ts:116 :116 — le test « catches every kind of violation on temporary fixtures, then is green again once they are removed ».
21test/arch/guard.test.ts:41 :41 — la première de treize fixtures ; chacune des douze règles en a au moins une, et la règle des cycles en a deux.
22docs/design.md:55 :55 — décision 10 : « Rejected: documentation and review only. Reviewers miss imports; CI does not. »
23docs/design.md:23 :23 — décision 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 — les arguments Docker commencent ici : --read-only, un tmpfs noexec, --cap-drop ALL, no-new-privileges, --user 10001:10001, --network, --memory, --pids-limit.
25services/memory/worker/sdk-agent.ts:51 :51 — les options de l’agent : strictMcpConfig: true, tools: [], allowedTools construit à partir des noms des outils internes, permissionMode: 'dontAsk', settingSources: [], persistSession: false, puis maxTurns et maxBudgetUsd tirés de la requête.
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 — décision 8, alternatives rejetées : lever une exception à travers la frontière du service, « the client cannot tell a bad input from a crashed worker », et faire confiance à la sortie du worker, « a prompt-injected agent could return anything ».
29docs/architecture.md:71 :71 — le type Result : un statut, les données, les preuves, l’identifiant du run, le coût, et une erreur quand le statut n’est pas ok.
30packages/contracts/src/result.ts:8 :8 — la liste fermée des codes d’erreur, de INVALID_INPUT à WORKER_OUTPUT_INVALID.
31docs/architecture.md:60 :60 — les étapes 1 à 6 de l’appel listent les événements d’un run : run.created, worker.started, worker.exited, output.validated ou 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 — décision 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 — les trois limites listées sous ce titre : le chemin SDK réel « needs the broker and an API key » ; les fichiers SQL ne rencontrent une vraie base « 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 — paquet agentic-ai, version 0.1.0.
39CHANGELOG.md:13 :13 — sous le seul titre, 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. »