# seratul03/aria architecture

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

- Interactive diagram: https://gitdiagram.com/seratul03/aria
- Repository: https://github.com/seratul03/aria

## Overview

ARIA is an autonomous agent that runs registered tools, records their outcomes, identifies weaknesses, and attempts safe improvements. Its main improvement path moves from the agent through introspection and code generation to evolutionary evaluation, Gatekeeper validation, and Git deployment; the README documents the candidate arena and referee as well. A separate meta-improvement path models system-wide weaknesses, modifies isolated clones, and compares them in an arena. Memory, knowledge, prediction, root-cause analysis, and reflection support these loops. Edges follow the README or shown source/index references; unsampled implementation details are not inferred.

Main entry points: [`aria/core/agent.py`](https://github.com/seratul03/aria/blob/main/aria/core/agent.py) (Agent Core), [`aria/introspection/meta.py`](https://github.com/seratul03/aria/blob/main/aria/introspection/meta.py) (Meta-Improvement), [`aria/introspection/engine.py`](https://github.com/seratul03/aria/blob/main/aria/introspection/engine.py) (Weakness Analysis), [`aria/evolution/arena.py`](https://github.com/seratul03/aria/blob/main/aria/evolution/arena.py) (Candidate Arena)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_agent["Agent Core<br/>[agent.py]"]
  node_scheduler["Priority Scheduler<br/>[scheduler.py]"]
  node_tools["Tool Registry<br/>[registry.py]"]
  node_toolset["Improvable Tools"]
  node_metrics[("Metrics Store<br/>[db.py]")]
  node_tracing["Cycle Tracing<br/>[tracer.py]"]
end

subgraph group_improve["Tool Improvement"]
  node_introspection["Weakness Analysis<br/>[engine.py]"]
  node_improvement["Improvement Engine<br/>[engine.py]"]
  node_evolution["Candidate Arena<br/>[arena.py]"]
  node_gatekeeper["Code Gatekeeper"]
  node_referee["Arena Referee<br/>[server.py]"]
  node_versioning["Git Deployment<br/>[git_manager.py]"]
end

subgraph group_meta["Meta Improvement"]
  node_meta["Meta-Improvement<br/>[meta.py]"]
  node_clone["Isolated Clones<br/>[clone.py]"]
  node_selfmodel["Self-Model and WTDS<br/>[self_model.py]"]
end

subgraph group_insights["Learning and Analysis"]
  node_memory[("Failure Memory<br/>[store.py]")]
  node_knowledge[("Engineering Knowledge<br/>[applications.py]")]
  node_predictors["Evolution Predictors<br/>[inference.py]"]
  node_rootcause["Root-Cause Analysis<br/>[classifier.py]"]
  node_reflection["Reflection Analysis<br/>[weaknesses.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Commands<br/>[cli.py]"]
  node_menu["Interactive Menu"]
end

node_user(("Operator"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses"| node_menu
node_cli -->|"dispatches tasks"| node_agent
node_menu -->|"controls"| node_agent
node_agent -->|"looks up tools"| node_tools
node_agent -->|"records executions"| node_metrics
node_tools -->|"registers"| node_toolset
node_agent -->|"selects targets"| node_scheduler
node_scheduler -->|"finds weaknesses"| node_introspection
node_introspection -->|"provides weakness report"| node_improvement
node_improvement -->|"generates candidates"| node_evolution
node_evolution -->|"validates candidates"| node_gatekeeper
node_evolution -->|"submits combat results"| node_referee
node_gatekeeper -->|"deploys accepted code"| node_versioning
node_referee -->|"deploys winner"| node_versioning
node_agent -->|"starts cycles"| node_introspection
node_agent -->|"checks viability"| node_predictors
node_predictors -->|"ranks candidates"| node_evolution
node_agent -->|"records cycle traces"| node_tracing
node_tracing -->|"persists traces"| node_metrics
node_introspection -->|"retrieves failure context"| node_memory
node_agent -->|"applies engineering rules"| node_knowledge
node_meta -->|"updates system model"| node_selfmodel
node_introspection -->|"analyzes traces"| node_selfmodel
node_meta -->|"creates isolated copies"| node_clone
node_clone -->|"competes in arena"| node_evolution
node_meta -->|"requests scoring"| node_referee
node_meta -->|"uses weakness findings"| node_reflection
node_meta -->|"uses root-cause findings"| node_rootcause

click node_cli "https://github.com/seratul03/aria/blob/main/aria/cli.py"
click node_menu "https://github.com/seratul03/aria/blob/main/aria/ui/interactive_menu.py"
click node_agent "https://github.com/seratul03/aria/blob/main/aria/core/agent.py"
click node_scheduler "https://github.com/seratul03/aria/blob/main/aria/core/scheduler.py"
click node_tools "https://github.com/seratul03/aria/blob/main/aria/tools/registry.py"
click node_toolset "https://github.com/seratul03/aria/tree/main/aria/tools"
click node_metrics "https://github.com/seratul03/aria/blob/main/aria/metrics/db.py"
click node_tracing "https://github.com/seratul03/aria/blob/main/aria/core/tracer.py"
click node_introspection "https://github.com/seratul03/aria/blob/main/aria/introspection/engine.py"
click node_improvement "https://github.com/seratul03/aria/blob/main/aria/improvement/engine.py"
click node_evolution "https://github.com/seratul03/aria/blob/main/aria/evolution/arena.py"
click node_gatekeeper "https://github.com/seratul03/aria/tree/main/aria/gatekeeper"
click node_referee "https://github.com/seratul03/aria/blob/main/aria/gatekeeper/referee/server.py"
click node_versioning "https://github.com/seratul03/aria/blob/main/aria/versioning/git_manager.py"
click node_meta "https://github.com/seratul03/aria/blob/main/aria/introspection/meta.py"
click node_clone "https://github.com/seratul03/aria/blob/main/aria/introspection/clone.py"
click node_selfmodel "https://github.com/seratul03/aria/blob/main/aria/introspection/self_model.py"
click node_memory "https://github.com/seratul03/aria/blob/main/aria/memory/store.py"
click node_knowledge "https://github.com/seratul03/aria/blob/main/aria/knowledge/applications.py"
click node_predictors "https://github.com/seratul03/aria/blob/main/aria/predictors/inference.py"
click node_rootcause "https://github.com/seratul03/aria/blob/main/aria/rootcause/classifier.py"
click node_reflection "https://github.com/seratul03/aria/blob/main/aria/reflection/weaknesses.py"

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_agent,node_scheduler,node_tools,node_toolset,node_metrics,node_tracing toneBlue
class node_introspection,node_improvement,node_evolution,node_gatekeeper,node_referee,node_versioning toneAmber
class node_meta,node_clone,node_selfmodel toneMint
class node_memory,node_knowledge,node_predictors,node_rootcause,node_reflection toneRose
class node_cli,node_menu,node_user toneIndigo
```

## Components

### Agent Runtime

- [Agent Core](https://github.com/seratul03/aria/blob/main/aria/core/agent.py): `aria/core/agent.py`
- [Priority Scheduler](https://github.com/seratul03/aria/blob/main/aria/core/scheduler.py): `aria/core/scheduler.py`
- [Tool Registry](https://github.com/seratul03/aria/blob/main/aria/tools/registry.py): `aria/tools/registry.py`
- [Improvable Tools](https://github.com/seratul03/aria/tree/main/aria/tools): `aria/tools`
- [Metrics Store](https://github.com/seratul03/aria/blob/main/aria/metrics/db.py): `aria/metrics/db.py`
- [Cycle Tracing](https://github.com/seratul03/aria/blob/main/aria/core/tracer.py): `aria/core/tracer.py`

### Tool Improvement

- [Weakness Analysis](https://github.com/seratul03/aria/blob/main/aria/introspection/engine.py): `aria/introspection/engine.py`
- [Improvement Engine](https://github.com/seratul03/aria/blob/main/aria/improvement/engine.py): `aria/improvement/engine.py`
- [Candidate Arena](https://github.com/seratul03/aria/blob/main/aria/evolution/arena.py): `aria/evolution/arena.py`
- [Code Gatekeeper](https://github.com/seratul03/aria/tree/main/aria/gatekeeper): `aria/gatekeeper`
- [Arena Referee](https://github.com/seratul03/aria/blob/main/aria/gatekeeper/referee/server.py): `aria/gatekeeper/referee/server.py`
- [Git Deployment](https://github.com/seratul03/aria/blob/main/aria/versioning/git_manager.py): `aria/versioning/git_manager.py`

### Meta Improvement

- [Meta-Improvement](https://github.com/seratul03/aria/blob/main/aria/introspection/meta.py): `aria/introspection/meta.py`
- [Isolated Clones](https://github.com/seratul03/aria/blob/main/aria/introspection/clone.py): `aria/introspection/clone.py`
- [Self-Model and WTDS](https://github.com/seratul03/aria/blob/main/aria/introspection/self_model.py): `aria/introspection/self_model.py`

### Learning and Analysis

- [Failure Memory](https://github.com/seratul03/aria/blob/main/aria/memory/store.py): `aria/memory/store.py`
- [Engineering Knowledge](https://github.com/seratul03/aria/blob/main/aria/knowledge/applications.py): `aria/knowledge/applications.py`
- [Evolution Predictors](https://github.com/seratul03/aria/blob/main/aria/predictors/inference.py): `aria/predictors/inference.py`
- [Root-Cause Analysis](https://github.com/seratul03/aria/blob/main/aria/rootcause/classifier.py): `aria/rootcause/classifier.py`
- [Reflection Analysis](https://github.com/seratul03/aria/blob/main/aria/reflection/weaknesses.py): `aria/reflection/weaknesses.py`

### User Interfaces

- [CLI Commands](https://github.com/seratul03/aria/blob/main/aria/cli.py): `aria/cli.py`
- [Interactive Menu](https://github.com/seratul03/aria/blob/main/aria/ui/interactive_menu.py): `aria/ui/interactive_menu.py`

### Other components

- **Operator**

## Connections

- Operator → CLI Commands: runs commands (evidence: `README.md`)
- Operator → Interactive Menu: uses (evidence: `README.md`)
- CLI Commands → Agent Core: dispatches tasks (evidence: `aria/cli.py`)
- Interactive Menu → Agent Core: controls (evidence: `aria/ui/interactive_menu.py`)
- Agent Core → Tool Registry: looks up tools (evidence: `aria/core/agent.py`)
- Agent Core → Metrics Store: records executions (evidence: `aria/core/agent.py`)
- Tool Registry → Improvable Tools: registers (evidence: `aria/tools/registry.py`)
- Agent Core → Priority Scheduler: selects targets (evidence: `README.md`)
- Priority Scheduler → Weakness Analysis: finds weaknesses (evidence: `README.md`)
- Weakness Analysis → Improvement Engine: provides weakness report (evidence: `aria/improvement/engine.py`)
- Improvement Engine → Candidate Arena: generates candidates (evidence: `README.md`)
- Candidate Arena → Code Gatekeeper: validates candidates (evidence: `README.md`)
- Candidate Arena → Arena Referee: submits combat results (evidence: `README.md`)
- Code Gatekeeper → Git Deployment: deploys accepted code (evidence: `README.md`)
- Arena Referee → Git Deployment: deploys winner (evidence: `README.md`)
- Agent Core → Weakness Analysis: starts cycles (evidence: `aria/core/agent.py`)
- Agent Core → Evolution Predictors: checks viability (evidence: `aria/core/agent.py`)
- Evolution Predictors → Candidate Arena: ranks candidates (evidence: `aria/predictors/inference.py`)
- Agent Core → Cycle Tracing: records cycle traces (evidence: `aria/core/agent.py`)
- Cycle Tracing → Metrics Store: persists traces (evidence: `aria/core/tracer.py`)
- Weakness Analysis → Failure Memory: retrieves failure context (evidence: `aria/introspection/engine.py`)
- Agent Core → Engineering Knowledge: applies engineering rules (evidence: `aria/core/agent.py`)
- Meta-Improvement → Self-Model and WTDS: updates system model (evidence: `README.md`)
- Weakness Analysis → Self-Model and WTDS: analyzes traces (evidence: `README.md`)
- Meta-Improvement → Isolated Clones: creates isolated copies (evidence: `README.md`)
- Isolated Clones → Candidate Arena: competes in arena (evidence: `README.md`)
- Meta-Improvement → Arena Referee: requests scoring (evidence: `README.md`)
- Meta-Improvement → Reflection Analysis: uses weakness findings (evidence: `aria/introspection/meta.py`)
- Meta-Improvement → Root-Cause Analysis: uses root-cause findings (evidence: `aria/introspection/meta.py`)
