# milodule3-debug/aura-code architecture

> Architecture diagram of the GitHub repository milodule3-debug/aura-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/milodule3-debug/aura-code
- Repository: https://github.com/milodule3-debug/aura-code

## Overview

1. **What this repo is**
   - Aura Code is a TypeScript autonomous coding agent. The runtime is a Node.js CLI/service that reads a project, decides on a strategy, edits files, runs tools/tests, and verifies results. The README’s modes reflect the top-level architecture: normal loop, multi-agent orchestration, architecture planning, verification, and failure analysis.

2. **Primary entrypoints**
   - The main execution surfaces are `src/cli`, `src/server`, and `src/workflows`.
   - `src/cli/index.ts` is the user-facing command entrypoint.
   - `src/server/index.ts` and `src/server/session.ts` suggest a server/session layer for longer-lived interactions.
   - `src/workflows/engine.ts` is the coordination layer for task execution flows.

3. **Core control loop**
   - `src/agent` contains the low-level agent lifecycle: context building, spawning, session persistence, system prompt definition, and the loop that repeatedly plans and acts.
   - This is the “single agent” execution path: gather context, prompt the model, invoke tools, capture results, and iterate.

4. **Multi-agent orchestration boundary**
   - `src/orchestration` is the higher-level coordination system. It appears to route work across specialist roles, manage competences, build plans, and execute those plans.
   - The presence of router/orchestrator/specialists/prompts/types indicates a structured split between decision-making and execution.
   - This layer is where “Researcher → Coder → Reviewer” style flows likely live.

5. **Architecture/planning subsystem**
   - `src/architect` is a distinct planning subsystem, separate from the agent loop and the orchestration layer.
   - It likely produces high-level designs and decomposes tasks before implementation, which is why it has its own engine and types.

6. **Perception and project understanding**
   - `src/perception` is the codebase analysis layer. It extracts repository structure and likely stores a graph/index of observed project facts.
   - `graph-store`, `queries`, and `extractor` indicate a read/derive/store pattern: inspect files, normalize the result, then query it for planning and prompting.
   - This subsystem feeds context into the agent/orchestrator so decisions are based on repository structure rather than only the raw prompt.

7. **Tooling boundary: how the agent acts**
   - `src/tools` is the action surface exposed to the model. It includes filesystem operations, shell execution, tests, browser/web access, search, image/audio/transcript helpers, memory, notifications, and messaging integrations.
   - This is the main side-effect boundary of the system: model decisions become tool calls, and tool results flow back into the agent loop.
   - The tool set is broad enough to support local code changes and external research/integration workflows.

8. **Provider abstraction**
   - `src/providers` isolates LLM backend differences behind a common interface.
   - There are adapters for Anthropic, Google, OpenAI-compatible providers, plus fallback and resilient wrappers.
   - This keeps the rest of the system provider-agnostic and lets the runtime survive transient provider failures.

9. **Safety and execution constraints**
   - `src/safety/permissions.ts` and utility layers like retry, circuit breaker, and rate limiter define operational guardrails.
   - These boundaries control what the agent can do, how failures are retried, and how external calls are stabilized.
   - The design is clearly meant to keep autonomous execution bounded and observable.

10. **Verification and quality gates**
   - `src/verify` performs post-action checks and has its own checks/types entrypoints.
   - The README’s “I don’t try. I verify.” is reflected in this subsystem: run changes, inspect outcomes, and confirm correctness before reporting success.
   - This is also where automated retry-on-failure behavior likely plugs in.

11. **Learning, episode capture, and “Ruby”**
   - `src/ruby` is a self-improvement / meta-learning subsystem, with competence modeling, episode capture, training data, alternation, and fine-tuning support.
   - It appears to analyze prior agent episodes and derive training or routing signals for future runs.
   - This is separate from normal task execution: it turns accumulated experience into improved behavior.

12. **Harnesses and weakness mining**
   - `src/harness` and `src/integrations/harnesses.ts` suggest a testing/benchmarking layer for generating or mining weaknesses from code/task examples.
   - This likely supports regression discovery and evaluation, complementing verification by exploring where the agent fails.

13. **Configuration, setup, and persistence**
   - `src/config`, `src/setup`, `src/util`, `src/versioncheck.ts`, and `src/agent/session-store.ts` handle defaults, project configuration, first-run behavior, environment parsing, and durable state.
   - These modules are the glue between runtime behavior and local installation state.
   - They define the boundary between “stateless prompt execution” and “persistent agent workspace/session behavior.”

14. **Observability and UX surfaces**
   - `src/viz` likely powers dashboards/visual reporting, while `graphify-out` contains generated artifacts for graph visualization.
   - The repo also includes packaged outputs and sample project assets under `my-project`, plus docs and generated media files.
   - For an architecture diagram, these are downstream outputs and supporting artifacts rather than core runtime components.

15. **Repo-level support material**
   - The `.agents`, `.qwen`, and related skill directories are a large knowledge/reference corpus for agent behavior and prompt/tooling patterns.
   - They are not the primary runtime, but they materially support how the system is used and extended.
   - In a diagram, treat them as documentation/skill assets feeding development and prompt design, not as live execution services.

16. **End-to-end flow to show in a diagram**
   - User command enters via CLI or server.
   - Configuration and permissions are loaded.
   - Perception builds repository context.
   - Orchestration/architect selects a plan and possibly specialist roles.
   - The agent loop invokes providers and tools to edit/run/inspect.
   - Verification checks the outcome.
   - Session/state stores the result, and reporting/viz surfaces summarize what happened.

Main entry points: [`src/agent/loop.ts`](https://github.com/milodule3-debug/aura-code/blob/main/src/agent/loop.ts) (Agent loop), [`src/orchestration/index.ts`](https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/index.ts) (Orchestration), [`src/server/index.ts`](https://github.com/milodule3-debug/aura-code/blob/main/src/server/index.ts) (Server), [`src/perception/index.ts`](https://github.com/milodule3-debug/aura-code/blob/main/src/perception/index.ts) (Perception)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Interfaces"]
  node_n1["CLI<br/>entrypoint<br/>[index.ts]"]
  node_n2["Server<br/>[index.ts]"]
end

subgraph group_g2["Core runtime"]
  node_n3["Workflow engine<br/>coordination<br/>[engine.ts]"]
  node_n4["Agent loop<br/>runtime loop<br/>[loop.ts]"]
  node_n5[("Session store<br/>persistence<br/>[session-store.ts]")]
end

subgraph group_g3["Understanding"]
  node_n6["Perception<br/>repo analysis<br/>[index.ts]"]
  node_n7[("Graph store<br/>index store<br/>[graph-store.ts]")]
  node_n8["Orchestration<br/>multi-agent<br/>[index.ts]"]
  node_n9["Architect<br/>planning<br/>[engine.ts]"]
  node_n10(("Router<br/>role dispatch<br/>[router.ts]"))
  node_n11["Executor<br/>role runner<br/>[executor.ts]"]
end

subgraph group_g4["Actuation"]
  node_n12["Provider layer<br/>llm adapters<br/>[factory.ts]"]
  node_n13["Tool surface<br/>actions<br/>[index.ts]"]
  node_n14{{"Permissions<br/>guardrails<br/>[permissions.ts]"}}
end

subgraph group_g5["Adaptation"]
  node_n15["Verification<br/>quality gate<br/>[index.ts]"]
  node_n16["Ruby learning<br/>meta-learning<br/>[index.ts]"]
  node_n17["Harnesses<br/>evaluation<br/>[proposer.ts]"]
end

subgraph group_g6["Support"]
  node_n18["Config<br/>[defaults.ts]"]
  node_n19["Viz<br/>reporting<br/>[index.ts]"]
  node_n20[("Global state<br/>setup<br/>[global-config.ts]")]
end

node_n1 -->|"loads config"| node_n18
node_n2 -->|"loads config"| node_n18
node_n1 -->|"starts"| node_n4
node_n2 -->|"serves"| node_n3
node_n3 -->|"orchestrates"| node_n8
node_n4 -->|"reads context"| node_n6
node_n6 -->|"stores facts"| node_n7
node_n4 -->|"calls model"| node_n12
node_n4 -->|"uses tools"| node_n13
node_n13 -->|"constrained by"| node_n14
node_n8 -->|"routes"| node_n10
node_n8 -->|"executes"| node_n11
node_n8 -->|"plans"| node_n9
node_n8 -->|"contextualizes"| node_n6
node_n15 -->|"verifies"| node_n4
node_n16 -->|"improves routing"| node_n8
node_n16 -->|"improves loop"| node_n4
node_n17 -->|"complements"| node_n15
node_n4 -->|"persists"| node_n5
node_n2 -->|"resumes"| node_n5
node_n19 -->|"summarizes"| node_n5
node_n20 -->|"feeds"| node_n18

click node_n1 "https://github.com/milodule3-debug/aura-code/blob/main/src/cli/index.ts"
click node_n2 "https://github.com/milodule3-debug/aura-code/blob/main/src/server/index.ts"
click node_n3 "https://github.com/milodule3-debug/aura-code/blob/main/src/workflows/engine.ts"
click node_n4 "https://github.com/milodule3-debug/aura-code/blob/main/src/agent/loop.ts"
click node_n5 "https://github.com/milodule3-debug/aura-code/blob/main/src/agent/session-store.ts"
click node_n6 "https://github.com/milodule3-debug/aura-code/blob/main/src/perception/index.ts"
click node_n7 "https://github.com/milodule3-debug/aura-code/blob/main/src/perception/graph-store.ts"
click node_n8 "https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/index.ts"
click node_n9 "https://github.com/milodule3-debug/aura-code/blob/main/src/architect/engine.ts"
click node_n10 "https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/router.ts"
click node_n11 "https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/executor.ts"
click node_n12 "https://github.com/milodule3-debug/aura-code/blob/main/src/providers/factory.ts"
click node_n13 "https://github.com/milodule3-debug/aura-code/blob/main/src/tools/index.ts"
click node_n14 "https://github.com/milodule3-debug/aura-code/blob/main/src/safety/permissions.ts"
click node_n15 "https://github.com/milodule3-debug/aura-code/blob/main/src/verify/index.ts"
click node_n16 "https://github.com/milodule3-debug/aura-code/blob/main/src/ruby/index.ts"
click node_n17 "https://github.com/milodule3-debug/aura-code/blob/main/src/harness/proposer.ts"
click node_n18 "https://github.com/milodule3-debug/aura-code/blob/main/src/config/defaults.ts"
click node_n19 "https://github.com/milodule3-debug/aura-code/blob/main/src/viz/index.ts"
click node_n20 "https://github.com/milodule3-debug/aura-code/blob/main/src/setup/global-config.ts"

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_n1,node_n2 toneBlue
class node_n3,node_n4,node_n5 toneAmber
class node_n6,node_n7,node_n8,node_n9,node_n10,node_n11 toneMint
class node_n12,node_n13,node_n14 toneRose
class node_n15,node_n16,node_n17 toneIndigo
class node_n18,node_n19,node_n20 toneTeal
```

## Components

### Interfaces

User-facing entrypoints and long-lived runtime surfaces

- [CLI](https://github.com/milodule3-debug/aura-code/blob/main/src/cli/index.ts): entrypoint · Command-line entrypoint for user commands · `src/cli/index.ts`
- [Server](https://github.com/milodule3-debug/aura-code/blob/main/src/server/index.ts): service · Long-lived server/session entrypoint · `src/server/index.ts`

### Core runtime

Agent loop and workflow coordination

- [Workflow engine](https://github.com/milodule3-debug/aura-code/blob/main/src/workflows/engine.ts): coordination · Coordinates task execution flows · `src/workflows/engine.ts`
- [Agent loop](https://github.com/milodule3-debug/aura-code/blob/main/src/agent/loop.ts): runtime loop · Single-agent plan-act-verify cycle · `src/agent/loop.ts`
- [Session store](https://github.com/milodule3-debug/aura-code/blob/main/src/agent/session-store.ts): persistence · Persists agent/session state · `src/agent/session-store.ts`

### Understanding

Repository analysis and planning subsystems

- [Perception](https://github.com/milodule3-debug/aura-code/blob/main/src/perception/index.ts): repo analysis · Extracts and queries repository structure · `src/perception/index.ts`
- [Graph store](https://github.com/milodule3-debug/aura-code/blob/main/src/perception/graph-store.ts): index store · Stores observed repository facts and structure · `src/perception/graph-store.ts`
- [Orchestration](https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/index.ts): multi-agent · Routes work across specialist roles · `src/orchestration/index.ts`
- [Architect](https://github.com/milodule3-debug/aura-code/blob/main/src/architect/engine.ts): planning · High-level design and task decomposition · `src/architect/engine.ts`
- [Router](https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/router.ts): role dispatch · Chooses the next specialist or path · `src/orchestration/router.ts`
- [Executor](https://github.com/milodule3-debug/aura-code/blob/main/src/orchestration/executor.ts): role runner · Runs orchestrated plans and specialist actions · `src/orchestration/executor.ts`

### Actuation

Tools, providers, and execution guardrails

- [Provider layer](https://github.com/milodule3-debug/aura-code/blob/main/src/providers/factory.ts): llm adapters · Abstracts model backends and resilience wrappers · `src/providers/factory.ts`
- [Tool surface](https://github.com/milodule3-debug/aura-code/blob/main/src/tools/index.ts): actions · Filesystem, shell, web, and integration tools · `src/tools/index.ts`
- [Permissions](https://github.com/milodule3-debug/aura-code/blob/main/src/safety/permissions.ts): guardrails · Operational safety and execution constraints · `src/safety/permissions.ts`

### Adaptation

Learning, verification, and failure feedback

- [Verification](https://github.com/milodule3-debug/aura-code/blob/main/src/verify/index.ts): quality gate · Checks results after actions complete · `src/verify/index.ts`
- [Ruby learning](https://github.com/milodule3-debug/aura-code/blob/main/src/ruby/index.ts): meta-learning · Episode capture, competence, and fine-tuning signals · `src/ruby/index.ts`
- [Harnesses](https://github.com/milodule3-debug/aura-code/blob/main/src/harness/proposer.ts): evaluation · Weakness mining and benchmark-style evaluation · `src/harness/proposer.ts`

### Support

Configuration, setup, persistence, and observability

- [Config](https://github.com/milodule3-debug/aura-code/blob/main/src/config/defaults.ts): runtime config · Defaults, project config, setup, and environment glue · `src/config/defaults.ts`
- [Viz](https://github.com/milodule3-debug/aura-code/blob/main/src/viz/index.ts): reporting · Dashboard and visual output surfaces · `src/viz/index.ts`
- [Global state](https://github.com/milodule3-debug/aura-code/blob/main/src/setup/global-config.ts): setup · First-run and global installation state · `src/setup/global-config.ts`

## Connections

- CLI → Config: loads config · CLI bootstraps runtime configuration
- Server → Config: loads config · Server startup uses project and global config
- CLI → Agent loop: starts · CLI enters the agent loop for a task
- Server → Workflow engine: serves · Server delegates long-lived work to workflows
- Workflow engine → Orchestration: orchestrates · Workflow engine hands execution to orchestration
- Agent loop → Perception: reads context · Agent loop gathers repository understanding
- Perception → Graph store: stores facts · Perception persists normalized repository graph data
- Agent loop → Provider layer: calls model · Agent loop invokes provider adapters for reasoning
- Agent loop → Tool surface: uses tools · Agent loop performs edits, searches, and checks through tools
- Tool surface → Permissions: constrained by · Tool execution is bounded by permissions and safety rules
- Orchestration → Router: routes · Orchestration selects specialists and next steps
- Orchestration → Executor: executes · Orchestration runs the chosen plan
- Orchestration → Architect: plans · Architect subsystem contributes higher-level decomposition
- Orchestration → Perception: contextualizes · Orchestration consults repository perception for decisions
- Verification → Agent loop: verifies · Verification validates outcomes produced by the loop
- Ruby learning → Orchestration: improves routing · Learning signals inform future orchestration behavior
- Ruby learning → Agent loop: improves loop · Captured episodes feed back into agent behavior
- Harnesses → Verification: complements · Harness evaluation supports verification and regression discovery
- Agent loop → Session store: persists · Loop stores session state and progress
- Server → Session store: resumes · Server session layer restores interaction state
- Viz → Session store: summarizes · Visualization surfaces session and run outcomes
- Global state → Config: feeds · Global setup informs configuration defaults and startup state