# anshulreddybuilds/aion-axon architecture

> Architecture diagram of the GitHub repository anshulreddybuilds/aion-axon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshulreddybuilds/aion-axon
- Repository: https://github.com/anshulreddybuilds/aion-axon

## Overview

AION AXON is a governed agent platform: it plans and executes missions through a controlled capability registry, and when a capability is missing, SYNAPSE researches, generates, screens, tests, and evaluates one before Guardian policy and human approval can allow installation. Missions can resume after approval. The API and React dashboard expose mission progress, capability evidence, approvals, monitoring, and audit history. The README documents the acquisition sequence; some internal wiring is inferred only where the SOURCE INDEX names the relationship, so unsampled details are omitted.

Main entry points: [`app/synapse/engine.py`](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/engine.py) (SYNAPSE loop), [`app/workflows/orchestrator.py`](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/workflows/orchestrator.py) (Tool orchestrator), [`app/api.py`](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/api.py) (API service), [`app/governance/guardian.py`](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/guardian.py) (Policy guardian)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mission["Mission execution"]
  node_planner["Mission planner<br/>[mission_planner.py]"]
  node_mission_service["Mission lifecycle<br/>[service.py]"]
  node_mission_engine["Step executor<br/>[engine.py]"]
  node_orchestrator["Tool orchestrator<br/>[orchestrator.py]"]
  node_workflow_state["Workflow state<br/>[state.py]"]
end

subgraph group_acquisition["Capability acquisition"]
  node_synapse["SYNAPSE loop<br/>[engine.py]"]
  node_research["Capability research<br/>[web_research.py]"]
  node_generator["Code generation<br/>[generator.py]"]
  node_safety["AST safety screen<br/>[safety_screen.py]"]
  node_sandbox["Isolated sandbox<br/>[main.py]"]
  node_evaluator["Independent evaluator<br/>[evaluator.py]"]
end

subgraph group_governance["Governance and evidence"]
  node_guardian["Policy guardian<br/>[guardian.py]"]
  node_approval["Human approval<br/>[approval.py]"]
  node_ledger["Autonomy ledger<br/>[autonomy_ledger.py]"]
  node_kill_switch["Kill switch<br/>[kill_switch.py]"]
  node_beastmode["Red-team security<br/>[red_team.py]"]
end

subgraph group_runtime["Capability runtime"]
  node_registry["Capability registry<br/>[registry.py]"]
  node_firestore[("Firestore persistence<br/>[firestore_store.py]")]
  node_monitor["Background monitors<br/>[service.py]"]
end

subgraph group_interface["API and dashboard"]
  node_api["API service<br/>[api.py]"]
  node_dashboard["React dashboard<br/>[App.jsx]"]
  node_api_client["Dashboard API client<br/>[api.js]"]
  node_pipeline_view["Acquisition stage view<br/>[livePipeline.js]"]
end

node_owner(("Owner"))

node_owner -->|"submits requests"| node_api
node_api -->|"routes missions"| node_mission_service
node_mission_service -->|"plans mission"| node_planner
node_mission_service -->|"runs or resumes"| node_mission_engine
node_mission_engine -->|"delegates steps"| node_orchestrator
node_orchestrator -->|"updates state"| node_workflow_state
node_mission_engine -.->|"signals capability gap"| node_synapse
node_synapse -->|"researches approach"| node_research
node_synapse -->|"generates candidate"| node_generator
node_synapse -->|"screens candidate"| node_safety
node_synapse -->|"tests candidate"| node_sandbox
node_synapse -->|"requests scoring"| node_evaluator
node_synapse -->|"checks policy"| node_guardian
node_synapse -->|"requests decision"| node_approval
node_owner -->|"approves or rejects"| node_approval
node_approval -->|"stores decision"| node_firestore
node_synapse -->|"installs capability"| node_registry
node_synapse -->|"records evolution"| node_ledger
node_synapse -->|"checks halt state"| node_kill_switch
node_guardian -->|"checks autonomy"| node_ledger
node_orchestrator -->|"resolves capability"| node_registry
node_orchestrator -->|"gates execution"| node_guardian
node_orchestrator -->|"handles approval"| node_approval
node_monitor -->|"executes scheduled checks"| node_orchestrator
node_api -->|"reads and writes records"| node_firestore
node_api -->|"serves monitor operations"| node_monitor
node_beastmode -->|"red-team references"| node_guardian
node_beastmode -->|"tests screening"| node_safety
node_dashboard -->|"loads dashboard data"| node_api_client
node_api_client -.->|"calls backend"| node_api
node_dashboard -.->|"renders acquisition stages"| node_pipeline_view

click node_api "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/api.py"
click node_planner "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/agents/mission_planner.py"
click node_mission_service "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/missions/service.py"
click node_mission_engine "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/missions/engine.py"
click node_orchestrator "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/workflows/orchestrator.py"
click node_workflow_state "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/workflows/state.py"
click node_synapse "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/engine.py"
click node_research "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/tools/web_research.py"
click node_generator "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/generator.py"
click node_safety "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/safety_screen.py"
click node_sandbox "https://github.com/anshulreddybuilds/aion-axon/blob/main/sandbox/main.py"
click node_evaluator "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/evaluator.py"
click node_guardian "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/guardian.py"
click node_approval "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/approval.py"
click node_ledger "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/autonomy_ledger.py"
click node_kill_switch "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/kill_switch.py"
click node_beastmode "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/beastmode/red_team.py"
click node_registry "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/capabilities/registry.py"
click node_firestore "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/memory/firestore_store.py"
click node_monitor "https://github.com/anshulreddybuilds/aion-axon/blob/main/app/monitors/service.py"
click node_dashboard "https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/App.jsx"
click node_api_client "https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/api.js"
click node_pipeline_view "https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/livePipeline.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_planner,node_mission_service,node_mission_engine,node_orchestrator,node_workflow_state toneBlue
class node_synapse,node_research,node_generator,node_safety,node_sandbox,node_evaluator toneAmber
class node_guardian,node_approval,node_ledger,node_kill_switch,node_beastmode toneMint
class node_registry,node_firestore,node_monitor toneRose
class node_api,node_dashboard,node_api_client,node_pipeline_view,node_owner toneIndigo
```

## Components

### Mission execution

- [Mission planner](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/agents/mission_planner.py): `app/agents/mission_planner.py`
- [Mission lifecycle](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/missions/service.py): `app/missions/service.py`
- [Step executor](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/missions/engine.py): `app/missions/engine.py`
- [Tool orchestrator](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/workflows/orchestrator.py): `app/workflows/orchestrator.py`
- [Workflow state](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/workflows/state.py): `app/workflows/state.py`

### Capability acquisition

- [SYNAPSE loop](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/engine.py): `app/synapse/engine.py`
- [Capability research](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/tools/web_research.py): `app/tools/web_research.py`
- [Code generation](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/generator.py): `app/synapse/generator.py`
- [AST safety screen](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/safety_screen.py): `app/synapse/safety_screen.py`
- [Isolated sandbox](https://github.com/anshulreddybuilds/aion-axon/blob/main/sandbox/main.py): `sandbox/main.py`
- [Independent evaluator](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/synapse/evaluator.py): `app/synapse/evaluator.py`

### Governance and evidence

- [Policy guardian](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/guardian.py): `app/governance/guardian.py`
- [Human approval](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/approval.py): `app/governance/approval.py`
- [Autonomy ledger](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/autonomy_ledger.py): `app/governance/autonomy_ledger.py`
- [Kill switch](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/governance/kill_switch.py): `app/governance/kill_switch.py`
- [Red-team security](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/beastmode/red_team.py): `app/beastmode/red_team.py`

### Capability runtime

- [Capability registry](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/capabilities/registry.py): `app/capabilities/registry.py`
- [Firestore persistence](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/memory/firestore_store.py): `app/memory/firestore_store.py`
- [Background monitors](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/monitors/service.py): `app/monitors/service.py`

### API and dashboard

- [API service](https://github.com/anshulreddybuilds/aion-axon/blob/main/app/api.py): `app/api.py`
- [React dashboard](https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Dashboard API client](https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/api.js): `web/src/api.js`
- [Acquisition stage view](https://github.com/anshulreddybuilds/aion-axon/blob/main/web/src/livePipeline.js): `web/src/livePipeline.js`

### Other components

- **Owner**

## Connections

- Owner → API service: submits requests (evidence: `README.md`)
- API service → Mission lifecycle: routes missions (evidence: `app/api.py`)
- Mission lifecycle → Mission planner: plans mission (evidence: `app/missions/service.py`)
- Mission lifecycle → Step executor: runs or resumes (evidence: `app/missions/service.py`)
- Step executor → Tool orchestrator: delegates steps (evidence: `app/missions/engine.py`)
- Tool orchestrator → Workflow state: updates state (evidence: `app/workflows/orchestrator.py`)
- Step executor → SYNAPSE loop: signals capability gap
- SYNAPSE loop → Capability research: researches approach (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Code generation: generates candidate (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → AST safety screen: screens candidate (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Isolated sandbox: tests candidate (evidence: `README.md`)
- SYNAPSE loop → Independent evaluator: requests scoring (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Policy guardian: checks policy (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Human approval: requests decision (evidence: `app/synapse/engine.py`)
- Owner → Human approval: approves or rejects (evidence: `README.md`)
- Human approval → Firestore persistence: stores decision (evidence: `app/governance/approval.py`)
- SYNAPSE loop → Capability registry: installs capability (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Autonomy ledger: records evolution (evidence: `app/synapse/engine.py`)
- SYNAPSE loop → Kill switch: checks halt state (evidence: `app/synapse/engine.py`)
- Policy guardian → Autonomy ledger: checks autonomy (evidence: `app/governance/guardian.py`)
- Tool orchestrator → Capability registry: resolves capability (evidence: `app/workflows/orchestrator.py`)
- Tool orchestrator → Policy guardian: gates execution (evidence: `app/workflows/orchestrator.py`)
- Tool orchestrator → Human approval: handles approval (evidence: `app/workflows/orchestrator.py`)
- Background monitors → Tool orchestrator: executes scheduled checks (evidence: `app/monitors/service.py`)
- API service → Firestore persistence: reads and writes records (evidence: `app/api.py`)
- API service → Background monitors: serves monitor operations (evidence: `app/api.py`)
- Red-team security → Policy guardian: red-team references (evidence: `app/beastmode/red_team.py`)
- Red-team security → AST safety screen: tests screening (evidence: `app/beastmode/red_team.py`)
- React dashboard → Dashboard API client: loads dashboard data (evidence: `web/src/App.jsx`)
- Dashboard API client → API service: calls backend
- React dashboard → Acquisition stage view: renders acquisition stages
