Docs · Architecture
How Project Orchestrator is built
Project Orchestrator is a server around a knowledge graph. People reach it through the dashboard, agents reach it through MCP, and the agents that do the work are started through an SDK that hides their differences.
What it does
The server keeps code, plans, notes, decisions and chat history in a graph database, and exposes them over REST, WebSocket and MCP.
The chat does not talk to one vendor. A provider resolver and the nexus SDK let the same session run on Claude Code, an OpenAI-compatible model, Codex or an ACP agent.
The dashboard is a separate project that speaks the same wire contract as any other client.
Claude Code is the default and the most tried engine. The native, Codex and ACP engines are alpha: they have been tested against stand-in programs, not against the real services yet.
The diagram
This overview is a summary drawn for this site from the backend README, the chat guide and the verified diagrams linked below. The backend does not yet have a verified overview diagram of its own, so treat it as a map, not as a proof.
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Flow diagram, left to right. On the left, the clients: the React dashboard, which uses REST and WebSocket, and MCP clients such as Claude Code, which go through the MCP server binary that calls the HTTP API. In the middle, the Rust server: the HTTP API, the ChatManager, the provider resolver, the agent runtime and a code parser. Below and to the right, the knowledge graph and services: Neo4j for code, plans, notes, decisions and chat events, Meilisearch for full-text search, and NATS for events and chat relay between instances. Top right, the nexus SDK: a provider registry, the agent contract and four providers, claude_code, native, codex and acp, which reach the Claude Code CLI, an OpenAI-compatible endpoint, codex app-server and any ACP agent.
Guided reading
Step 1. Clients
The dashboard connects over REST and a WebSocket per chat session. MCP clients such as Claude Code use the MCP server, a separate binary that calls the HTTP API.
Step 2. The server
The HTTP API serves REST and two WebSocket endpoints (chat and live CRUD events). The ChatManager owns chat sessions: replay, broadcast and routing of what you type.
Step 3. The knowledge graph
Neo4j holds code, plans, notes, decisions and the persisted chat events. Meilisearch indexes code, decisions and messages for search. A tree-sitter based parser reads your code and writes it to the graph.
Step 4. Several instances
NATS relays events and chat between instances, so a session can run on one instance while a client is attached to another.
Step 5. Picking an agent
For each session, the provider resolver chooses a provider by an ordered rule, and the agent runtime drives it turn by turn.
Step 6. The agent SDK
The nexus SDK defines the agent contract, keeps a registry of provider instances and implements four adapters. Behind them are the real agents and model endpoints.
Why it is built this way
A graph, not a pile of files
Plans, tasks, notes, decisions and code live as linked nodes, so an agent can ask what touches this file or which decision explains that choice instead of rereading text.
A neutral contract at the seam
The only place that knows a vendor protocol is an adapter. Everything above it, from the chat to the dashboard, speaks neutral events.
Separate repositories, shared contracts
The server, the SDK and the dashboard are separate repositories. They stay in step through committed contracts: JSON fixtures with checksums for the chat wire format, and snapshot tests for the agent contract.
Safety is part of the design
Secrets are references, events are masked before they are stored, graph text put in a prompt is fenced as data, an approval you give for a session or for good is kept and checked by PO and never handed to the engine, agent sessions get narrow tokens and a child can never be more permissive than its parent.
Public sources
Where to check each statement, in the public repositories.