Aller au contenu

Docs · Architecture

Comment Project Orchestrator est construit

Project Orchestrator est un serveur autour d'un graphe de connaissances. Les personnes y accèdent par le tableau de bord, les agents par MCP, et les agents qui font le travail sont lancés par un SDK qui masque leurs différences.

Ce que ça fait

Le serveur garde le code, les plans, les notes, les décisions et l'historique des chats dans une base de graphe, et les expose en REST, en WebSocket et en MCP.

Le chat ne parle pas à un seul fournisseur. Un résolveur de provider et le SDK nexus font tourner la même session sur Claude Code, un modèle compatible OpenAI, Codex ou un agent ACP.

Le tableau de bord est un projet à part qui parle le même contrat de fil que n'importe quel autre client.

Claude Code est le moteur par défaut et le plus éprouvé. Les moteurs natif, Codex et ACP sont en alpha : ils ont été testés contre des programmes de remplacement, pas encore contre les vrais services.

Le schéma

Cette vue d'ensemble est un résumé dessiné pour ce site à partir du README du backend, du guide du chat et des diagrammes vérifiés liés plus bas. Le backend n'a pas encore de diagramme d'ensemble vérifié : prends-la comme une carte, pas comme une preuve.

Vue d'ensemble de l'architectureSchéma de flux, de gauche à droite. À gauche, les clients : le tableau de bord React, qui utilise REST et WebSocket, et les clients MCP comme Claude Code, qui passent par le binaire du serveur MCP, lequel appelle l'API HTTP. Au milieu, le serveur Rust : l'API HTTP, le ChatManager, le résolveur de provider, le runtime d'agent et un analyseur de code. En dessous et à droite, le graphe de connaissances et les services : Neo4j pour le code, les plans, les notes, les décisions et les événements de chat, Meilisearch pour la recherche plein texte, et NATS pour les événements et le relais du chat entre instances. En haut à droite, le SDK nexus : un registre de providers, le contrat d'agent et quatre providers, claude_code, native, codex et acp, qui atteignent le CLI Claude Code, un endpoint compatible OpenAI, codex app-server et n'importe quel agent ACP.nexus-claude SDK (nexus repository)Knowledge graph and servicesREST + WebSocketMCPAgents and modelsClaude Code CLIOpenAI-compatibleendpointcodex app-serverACP agentServer (Rust, backend repository)HTTPHTTP APIREST, /ws/chat, /ws/eventsMCP servermcp_server binaryChatManagersessions, replay, broadcastProvider resolverAgentRuntimeCode parsertree-sitterClientsDashboardReactMCP clientsClaude Code, Cursor, ...Neo4jcode, plans, notes,decisions, chat eventsMeilisearchfull-text searchNATSevents, chat relaybetween instancesProviderRegistryAgentProvider / AgentSessionAgentEvent, ToolPolicy, Capabilitiesclaude_codenativecodexacp

Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.

DézoomerZoomerPlein écran
Dessiné pour ce site à partir des sources listées plus bas. Les libellés sont les noms utilisés dans le code.
Description textuelle du schéma

Schéma de flux, de gauche à droite. À gauche, les clients : le tableau de bord React, qui utilise REST et WebSocket, et les clients MCP comme Claude Code, qui passent par le binaire du serveur MCP, lequel appelle l'API HTTP. Au milieu, le serveur Rust : l'API HTTP, le ChatManager, le résolveur de provider, le runtime d'agent et un analyseur de code. En dessous et à droite, le graphe de connaissances et les services : Neo4j pour le code, les plans, les notes, les décisions et les événements de chat, Meilisearch pour la recherche plein texte, et NATS pour les événements et le relais du chat entre instances. En haut à droite, le SDK nexus : un registre de providers, le contrat d'agent et quatre providers, claude_code, native, codex et acp, qui atteignent le CLI Claude Code, un endpoint compatible OpenAI, codex app-server et n'importe quel agent ACP.

Lecture guidée

  1. Étape 1. Les clients

    Le tableau de bord se connecte en REST et par un WebSocket par session de chat. Les clients MCP comme Claude Code passent par le serveur MCP, un binaire à part qui appelle l'API HTTP.

  2. Étape 2. Le serveur

    L'API HTTP sert le REST et deux WebSocket (le chat et les événements CRUD en direct). Le ChatManager possède les sessions de chat : rejeu, diffusion et routage de ce que tu écris.

  3. Étape 3. Le graphe de connaissances

    Neo4j contient le code, les plans, les notes, les décisions et les événements de chat persistés. Meilisearch indexe le code, les décisions et les messages pour la recherche. Un analyseur fondé sur tree-sitter lit ton code et l'écrit dans le graphe.

  4. Étape 4. Plusieurs instances

    NATS relaie les événements et le chat entre instances : une session peut tourner sur une instance pendant qu'un client est branché sur une autre.

  5. Étape 5. Choisir un agent

    Pour chaque session, le résolveur de provider choisit un provider selon une règle ordonnée, et le runtime d'agent le pilote tour par tour.

  6. Étape 6. Le SDK d'agents

    Le SDK nexus définit le contrat d'agent, tient un registre d'instances de providers et implémente quatre adaptateurs. Derrière : les vrais agents et les endpoints de modèles.

Pourquoi c'est conçu ainsi

Un graphe, pas un tas de fichiers

Plans, tâches, notes, décisions et code vivent comme des nœuds liés : un agent peut demander ce qui touche ce fichier ou quelle décision explique ce choix, au lieu de relire du texte.

Un contrat neutre à la couture

Le seul endroit qui connaît un protocole de fournisseur est un adaptateur. Tout ce qui est au-dessus, du chat au tableau de bord, parle en événements neutres.

Des dépôts séparés, des contrats partagés

Le serveur, le SDK et le tableau de bord sont des dépôts séparés. Ils restent alignés par des contrats versionnés : fixtures JSON avec sommes de contrôle pour le format du chat, tests d'instantanés pour le contrat d'agent.

La sécurité fait partie du dessin

Les secrets sont des références, les événements sont masqués avant d'être stockés, le texte du graphe mis dans une invite est isolé comme donnée, une autorisation donnée pour la session ou pour toujours est gardée et vérifiée par PO et jamais remise au moteur, les sessions d'agent reçoivent des jetons étroits et un enfant ne peut jamais être plus permissif que son parent.

Pour continuer

Le détail, un schéma à la fois

InternalsUn contrat pour tous les agents de codeLe petit jeu de types par lequel on atteint tout agent de code : providers, sessions, événements, politiques, capacités.InternalsQuatre façons de lancer un agent, une seule suite de testsClaude Code, un harnais natif sur des endpoints compatibles OpenAI, Codex et ACP : en quoi ils diffèrent et comment une suite de tests les garde honnêtes.InternalsQuel provider fait tourner cette session ?La règle ordonnée qui choisit le provider d'une session de chat, et quand elle a le droit de changer d'avis.InternalsRoutage cognitif : comment un modèle est choisiTrois modes de routage, une étape qui enregistre avant d'agir, et des décisions que l'on peut lire et rejouer.InternalsComment le chat arrive jusqu'à ton écranUn WebSocket par session de chat : authentification, rejeu depuis le dernier événement vu, puis le flux en direct.InternalsCe qui se passe dans un tour d'agentCe que fait le chat autour d'un tour d'agent : file, persistance, masquage, nouvel essai, conversion, diffusion, plus les portées de permission et la chronologie des outils.InternalsComment un agent qui lance des agents reste dans ses limitesComment une session ouverte par un agent reçoit un jeton révocable et une enveloppe qui ne peut que restreindre son parent.InternalsOù s'arrête Claude Code, où commence n'importe quel agentOù le SDK cesse d'être un client Claude Code pour devenir un SDK d'agents, et le faux CLI qui le spécifie.InternalsComment un changement devient une versionLes contrôles que passe chaque changement dans le dépôt nexus, et comment un tag devient archives et crates.