Proposal: standalone high-level architecture diagram

[itamarsb]

## Proposal: standalone high-level architecture diagram

Hello Tyler,

I recently discovered Arbiter and have been studying its documentation and overall architecture.

The written documentation explains the individual concepts and interfaces in detail, but as a first-time visitor, I initially found it difficult to form a high-level mental model of how the main parts relate to one another—for example:

* the TUI, one-shot CLI, and HTTP/SSE interfaces;
* the main orchestration flow;
* specialist agents and the optional advisor;
* the shared event model;
* persistent memory and request history;
* tools, MCP servers, A2A agents, and model providers.

Would you be interested in a small documentation contribution adding a standalone high-level architecture diagram written in Mermaid?

My intention would be to:

* add a separate Markdown file under `docs/`;
* avoid restructuring or expanding the main README;
* keep the diagram conceptual rather than implementation-specific;
* link to the existing documentation as the authoritative source;
* submit only the diagram and a short explanation in the pull request.

Before preparing it, I would appreciate your guidance on two points:

1. Which documentation directory would be the most appropriate location?
2. Which components or relationships should appear—or should deliberately not appear—in a high-level diagram?

I would be happy to prepare an initial Mermaid draft for architectural review before opening a pull request.

Thank you for making Arbiter available as an open-source project.

[tylerreckart]

Hello!

A standalone high-level Mermaid diagram under docs/ sounds useful. The README and concept pages explain the pieces well, but they don’t give a first-time visitor a single picture of how those pieces hang together. Keeping it conceptual, linking out to the existing docs, and leaving the README alone is exactly the right scope.

This should be located under docs/concepts.

Worth showing at this level:

• One binary, three faces — TUI, one-shot CLI (--send), HTTP+SSE (--api)
• Shared orchestration loop / streaming event bus (same event model everywhere)
• Agents driven by constitutions (model, role, rules, tool allowlist)
• Writ as the agent→runtime command surface (conceptually; not every /cmd)
• Optional advisor gate on the path
• Persistent store under ~/.arbiter/ — conversations / request history, structured memory
• Outbound edges: model providers, tools / MCP servers, A2A agents
• Tenants as an API-mode isolation boundary (a small annotation is enough)

Omit or keep off the main diagram:

• Implementation internals (languages, storage engine, class/module names)
• Full writ inventory, endpoint catalogs, or data-model field schemas
• TUI chrome (panes, themes, keybindings)
• Secondary surfaces that are easy to over-weight: scheduler, sandbox details, search providers, fleet multiplexing, admin/metrics — at most a light “also see …” footnote, not peer boxes