# MirrorNeuron Architecture (/docs/architect)
# MirrorNeuron Architecture [#mirrorneuron-architecture]
MirrorNeuron is designed as an Elixir/BEAM runtime for orchestrating multi-agent workflows with bounded sandbox execution. Currently, the `mn` CLI and the HTTP API act as two shells interfacing directly with the internal core components.
In the future, introducing a unified SDK layer would abstract these internal interfaces, allowing both the CLI and the Web API to consume the same stable public boundary.
## System Context [#system-context]
The overall system architecture involves the Developer/Operator interacting with MirrorNeuron, which in turn manages execution via OpenShell.
```mermaid
graph LR
linkStyle default fill:#ffffff
subgraph diagram ["System Context View: MirrorNeuron"]
style diagram fill:#ffffff,stroke:#ffffff
1["Developer / Operator
[Person]
Interacts with MirrorNeuron
to submit jobs, monitor
execution, and manage the
cluster.
"]
style 1 fill:#08427b,stroke:#052e56,color:#ffffff
15("OpenShell
[Software System]
Provides bounded sandbox
execution environments.
")
style 15 fill:#1168bd,stroke:#0b4884,color:#ffffff
2("MirrorNeuron
[Software System]
Elixir/BEAM runtime for
orchestrating multi-agent
workflows with bounded
sandbox execution.
")
style 2 fill:#1168bd,stroke:#0b4884,color:#ffffff
1-. "Uses for terminal operations
" .->2
2-. "Executes commands in isolated
sandboxes
" .->15
end
```
## Containers [#containers]
Zooming in, we see the main components that make up MirrorNeuron:
* **CLI Tool (mn)**: Terminal-first interface.
* **REST API**: HTTP API.
* **Core Runtime**: Built on Elixir/BEAM, handles orchestration and state.
* **Sandbox Manager**: Handles OpenShell interaction.
* **Persistence Store**: Redis for state.
```mermaid
graph LR
linkStyle default fill:#ffffff
subgraph diagram ["Container View: MirrorNeuron"]
style diagram fill:#ffffff,stroke:#ffffff
1["Developer / Operator
[Person]
Interacts with MirrorNeuron
to submit jobs, monitor
execution, and manage the
cluster.
"]
style 1 fill:#08427b,stroke:#052e56,color:#ffffff
15("OpenShell
[Software System]
Provides bounded sandbox
execution environments.
")
style 15 fill:#1168bd,stroke:#0b4884,color:#ffffff
subgraph 2 ["MirrorNeuron"]
style 2 fill:#ffffff,stroke:#0b4884,color:#0b4884
11("Sandbox Manager
[Container: Elixir]
Manages the lifecycle of
OpenShell sandboxes for
isolated execution.
")
style 11 fill:#438dd5,stroke:#2e6295,color:#ffffff
14("Persistence Store
[Container: Redis]
Stores job state, agent
snapshots, and event history.
")
style 14 fill:#438dd5,stroke:#2e6295,color:#ffffff
3("CLI Tool (mn)
[Container: Elixir Escript]
Provides terminal-first
tooling for interacting with
MirrorNeuron.
")
style 3 fill:#438dd5,stroke:#2e6295,color:#ffffff
4("REST API
[Container: Plug / Bandit]
HTTP API for inspection,
control, and external
integration (e.g., Web UI).
")
style 4 fill:#438dd5,stroke:#2e6295,color:#ffffff
5("Core Runtime
[Container: Elixir / BEAM]
Handles orchestration,
supervision, message routing,
clustering, and persistence.
")
style 5 fill:#438dd5,stroke:#2e6295,color:#ffffff
end
1-. "Uses for terminal operations
" .->3
1-. "Uses via Web UI or scripts
" .->4
3-. "Submits jobs, monitors,
controls via Erlang RPC
" .->5
4-. "Inspects and controls via
Elixir API
" .->5
5-. "Persists state, events, and
metrics
" .->14
5-. "Requests execution of agent
logic
" .->11
11-. "Executes commands in isolated
sandboxes
" .->15
end
```
## Core Runtime Components [#core-runtime-components]
The core logic within the BEAM node relies on several GenServers and internal modules to route messages and coordinate jobs.
```mermaid
graph LR
linkStyle default fill:#ffffff
subgraph diagram ["Component View: MirrorNeuron - Core Runtime"]
style diagram fill:#ffffff,stroke:#ffffff
subgraph 2 ["MirrorNeuron"]
style 2 fill:#ffffff,stroke:#0b4884,color:#0b4884
subgraph 5 ["Core Runtime"]
style 5 fill:#ffffff,stroke:#2e6295,color:#2e6295
10("Lease Manager
[Component: GenServer]
Manages execution leases to
bound sandbox capacity.
")
style 10 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
6("Job Coordinator
[Component: GenServer]
Manages the lifecycle of a
job, including starting
agents, handling terminal
states, and cleanup.
")
style 6 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
7("Agent Worker
[Component: GenServer]
Represents a logical agent in
a workflow, holds state, and
coordinates with OpenShell
for execution.
")
style 7 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
8("Message Router
[Component: Elixir]
Routes messages between
agents within the same job.
")
style 8 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
9("Event Bus
[Component: Registry]
Publishes and subscribes to
job-related events.
")
style 9 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
end
end
6-. "Supervises and controls
" .->7
7-. "Sends and receives messages
" .->8
6-. "Publishes lifecycle events
" .->9
7-. "Publishes state changes and
errors
" .->9
7-. "Requests execution leases
" .->10
end
```
## Sandbox Manager Components [#sandbox-manager-components]
The component that bridges Elixir space to the external OpenShell environments.
```mermaid
graph LR
linkStyle default fill:#ffffff
subgraph diagram ["Component View: MirrorNeuron - Sandbox Manager"]
style diagram fill:#ffffff,stroke:#ffffff
subgraph 2 ["MirrorNeuron"]
style 2 fill:#ffffff,stroke:#0b4884,color:#0b4884
subgraph 11 ["Sandbox Manager"]
style 11 fill:#ffffff,stroke:#2e6295,color:#2e6295
12("Job Sandbox
[Component: Elixir]
Interfaces with OpenShell to
create, manage, and execute
commands within a sandbox.
")
style 12 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
13("OpenShell Client
[Component: System.cmd]
Low-level client for
interacting with the
OpenShell CLI/Daemon.
")
style 13 fill:#85bbf0,stroke:#5d82a8,color:#ffffff
end
end
12-. "Uses to interact with
OpenShell
" .->13
end
```