Design Diagram
This diagram is a first-class project artifact. It shows all currently implemented types and their relationships, organized by source module.
The authoritative source is docs/diagrams/uml/diagram-detailed.d2 (D2 format).
Per-module diagrams and the module overview are auto-generated from this source
and rendered with the ELK layout engine (bundled with D2). Every PR that touches
src/agentrelay/ must update the diagram to reflect any new or changed types
and relationships, then re-render via pixi run diagram.
Views
Module overview — inter-module dependency graph. One box per module, arrows showing which modules depend on which. This is the best starting point for understanding the architecture.
View module overview (SVG) — opens in a new tab with native browser pan/zoom (Ctrl+scroll).
Per-module diagrams — each module gets a focused diagram showing its full
types plus simplified stubs for external dependencies. Located in
diagrams/uml/modules/diagram-{module-name}.svg. These are the primary
reference for understanding individual modules.
Per-module diagrams are auto-generated from diagram-detailed.d2 by
tools/generate_module_diagrams.py. External dependency stubs are shown at
reduced opacity with only the types that have relationships with the focus
module.
| Module | Diagram |
|---|---|
| agent/ | diagram-agent.svg |
| agent_comm_protocol/ | diagram-agent-comm-protocol.svg |
| agent_sdk/ | diagram-agent-sdk.svg |
| environments.py | diagram-environments.svg |
| errors/ | diagram-errors.svg |
| graph_index.py | diagram-graph-index.svg |
| ops/ | diagram-ops.svg |
| orchestrator/ | diagram-orchestrator.svg |
| output/ | diagram-output.svg |
| reset_graph.py | diagram-reset-graph.svg |
| reset_ops.py | diagram-reset-ops.svg |
| reset_pr.py | diagram-reset-pr.svg |
| reset_repo.py | diagram-reset-repo.svg |
| reset_task.py | diagram-reset-task.svg |
| reset_to.py | diagram-reset-to.svg |
| reset_workstream.py | diagram-reset-workstream.svg |
| run_graph.py | diagram-run-graph.svg |
| run_repo.py | diagram-run-repo.svg |
| sandbox/ | diagram-sandbox.svg |
| session.py | diagram-session.svg |
| task.py | diagram-task.svg |
| task_graph/ | diagram-task-graph.svg |
| task_runner/ | diagram-task-runner.svg |
| task_runtime/ | diagram-task-runtime.svg |
| tools.py | diagram-tools.svg |
| workstream/ | diagram-workstream.svg |
Conventions
Connector lines represent relationships that are not already obvious from the class body or visual proximity. Guidelines:
- Always add connectors for composition/ownership and inheritance/implementation.
- Omit connectors when return types reference types that are already visually adjacent and connected via other relationships.
- When in doubt, prefer fewer connectors — the diagram should highlight structural relationships, not restate every type signature.