# coder1317/aria architecture

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

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

## Overview

ARIA is a local-first autonomous engineering assistant. A terminal user or Telegram message enters the Brain orchestrator, which selects research, market, build, improve, or runtime work; build requests progress through architecture, code generation, review/security checks, debugging, tests, and project delivery. Separate branches provide deployment, persistent background tasks, API access, scheduling, and proactive event-driven actions. The tree and excerpts establish several calls directly; README-documented features with unsampled internals are shown at their supported enclosing paths, without speculative wiring.

Main entry points: [`ultra/orchestrator.py`](https://github.com/coder1317/aria/blob/master/ultra/orchestrator.py) (Brain orchestrator), [`ultra/agents/engineering.py`](https://github.com/coder1317/aria/blob/master/ultra/agents/engineering.py) (Engineering pipeline), [`ultra/agents/research.py`](https://github.com/coder1317/aria/blob/master/ultra/agents/research.py) (Research agent), [`ultra/core/tool_registry.py`](https://github.com/coder1317/aria/blob/master/ultra/core/tool_registry.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_orchestrator["Brain orchestrator<br/>[orchestrator.py]"]
  node_intent["Intent routing<br/>[intent.py]"]
end

subgraph group_agents["Agent workflows"]
  node_research_agent["Research agent<br/>[research.py]"]
  node_market_agent["Market agent<br/>[market.py]"]
  node_engineering["Engineering pipeline<br/>[engineering.py]"]
  node_architect["Architecture planning<br/>[architect.py]"]
  node_coder["Code generation<br/>[coder.py]"]
  node_reviewer["Code review<br/>[reviewer.py]"]
  node_debugger["Issue repair<br/>[debugger.py]"]
  node_tester["Test execution<br/>[tester.py]"]
  node_evaluator["Build evaluation<br/>[evaluator.py]"]
  node_deployer["Deployment generation<br/>[deployer.py]"]
  node_trainer["Skill extraction<br/>[trainer.py]"]
end

subgraph group_runtime["Runtime and memory"]
  node_provider_pool["Provider pool<br/>[provider_pool.py]"]
  node_task_manager[("Background task queue<br/>[task_manager.py]")]
  node_runtime_engine["Plan-act runtime<br/>[runtime.py]"]
  node_tool_registry["Tool registry<br/>[tool_registry.py]"]
  node_memory[("Memory and skills<br/>[memory.py]")]
  node_vectors[("Vector store<br/>[vectors.py]")]
  node_event_bus["Event bus<br/>[events.py]"]
  node_policy["Event policies<br/>[policy_engine.py]"]
  node_watchers["File watchers<br/>[watchers.py]"]
  node_goals[("Goal manager<br/>[goals.py]")]
end

subgraph group_integrations["Channels and integrations"]
  node_telegram["Telegram adapter<br/>[telegram.py]"]
  node_ollama["Local Ollama<br/>[llm.py]"]
  node_web_research["Web search and fetch<br/>[researcher.py]"]
  node_tools["Built-in tools"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_governance["Security and operations"]
  node_security["Security scanning<br/>[security.py]"]
  node_audit[("Audit log<br/>[audit.py]")]
end

node_user(("Terminal user"))
node_telegram_user(("Telegram user"))

node_user -->|"submits request"| node_cli
node_telegram_user -->|"sends message"| node_telegram
node_telegram -->|"dispatches message"| node_orchestrator
node_cli -->|"dispatches request"| node_orchestrator
node_orchestrator -->|"classifies intent"| node_intent
node_orchestrator -->|"requests model work"| node_provider_pool
node_provider_pool -->|"routes locally"| node_ollama
node_orchestrator -->|"dispatches research"| node_research_agent
node_research_agent -->|"searches and fetches"| node_web_research
node_research_agent -->|"synthesizes report"| node_provider_pool
node_orchestrator -->|"dispatches analysis"| node_market_agent
node_orchestrator -->|"starts build"| node_engineering
node_engineering -->|"plans project"| node_architect
node_engineering -->|"generates files"| node_coder
node_engineering -->|"reviews code"| node_reviewer
node_engineering -->|"scans generated code"| node_security
node_engineering -->|"repairs issues"| node_debugger
node_engineering -->|"runs tests"| node_tester
node_orchestrator -->|"scores build"| node_evaluator
node_orchestrator -->|"dispatches deployment"| node_deployer
node_orchestrator -->|"extracts skills"| node_trainer
node_orchestrator -->|"submits background work"| node_task_manager
node_task_manager -->|"runs registered handlers"| node_orchestrator
node_orchestrator -->|"creates and runs plan"| node_runtime_engine
node_runtime_engine -->|"executes tool calls"| node_tool_registry
node_tool_registry -->|"dispatches tools"| node_tools
node_tool_registry -.->|"invokes external tools"| node_mcp
node_orchestrator -->|"reads and updates"| node_memory
node_orchestrator -->|"uses embeddings"| node_vectors
node_watchers -->|"emits file events"| node_event_bus
node_event_bus -->|"dispatches events"| node_policy
node_policy -->|"submits event tasks"| node_task_manager
node_policy -->|"sends alerts"| node_notifications
node_goals -->|"publishes goal events"| node_event_bus
node_orchestrator -->|"records operations"| node_audit
node_orchestrator -->|"sends updates"| node_notifications

click node_cli "https://github.com/coder1317/aria/blob/master/ultra/cli.py"
click node_telegram "https://github.com/coder1317/aria/blob/master/ultra/channels/telegram.py"
click node_orchestrator "https://github.com/coder1317/aria/blob/master/ultra/orchestrator.py"
click node_intent "https://github.com/coder1317/aria/blob/master/ultra/intent.py"
click node_provider_pool "https://github.com/coder1317/aria/blob/master/ultra/provider_pool.py"
click node_ollama "https://github.com/coder1317/aria/blob/master/ultra/llm.py"
click node_research_agent "https://github.com/coder1317/aria/blob/master/ultra/agents/research.py"
click node_web_research "https://github.com/coder1317/aria/blob/master/ultra/tools/researcher.py"
click node_market_agent "https://github.com/coder1317/aria/blob/master/ultra/agents/market.py"
click node_engineering "https://github.com/coder1317/aria/blob/master/ultra/agents/engineering.py"
click node_architect "https://github.com/coder1317/aria/blob/master/ultra/agents/architect.py"
click node_coder "https://github.com/coder1317/aria/blob/master/ultra/agents/coder.py"
click node_reviewer "https://github.com/coder1317/aria/blob/master/ultra/agents/reviewer.py"
click node_security "https://github.com/coder1317/aria/blob/master/ultra/security.py"
click node_debugger "https://github.com/coder1317/aria/blob/master/ultra/agents/debugger.py"
click node_tester "https://github.com/coder1317/aria/blob/master/ultra/agents/tester.py"
click node_evaluator "https://github.com/coder1317/aria/blob/master/ultra/evaluator.py"
click node_deployer "https://github.com/coder1317/aria/blob/master/ultra/agents/deployer.py"
click node_trainer "https://github.com/coder1317/aria/blob/master/ultra/agents/trainer.py"
click node_task_manager "https://github.com/coder1317/aria/blob/master/ultra/task_manager.py"
click node_runtime_engine "https://github.com/coder1317/aria/blob/master/ultra/core/runtime.py"
click node_tool_registry "https://github.com/coder1317/aria/blob/master/ultra/core/tool_registry.py"
click node_tools "https://github.com/coder1317/aria/tree/master/ultra/tools"
click node_mcp "https://github.com/coder1317/aria/blob/master/ultra/tools/mcp_client.py"
click node_memory "https://github.com/coder1317/aria/blob/master/ultra/core/memory.py"
click node_vectors "https://github.com/coder1317/aria/blob/master/ultra/core/vectors.py"
click node_event_bus "https://github.com/coder1317/aria/blob/master/ultra/core/events.py"
click node_policy "https://github.com/coder1317/aria/blob/master/ultra/core/policy_engine.py"
click node_watchers "https://github.com/coder1317/aria/blob/master/ultra/core/watchers.py"
click node_goals "https://github.com/coder1317/aria/blob/master/ultra/core/goals.py"
click node_notifications "https://github.com/coder1317/aria/blob/master/ultra/core/notifications.py"
click node_audit "https://github.com/coder1317/aria/blob/master/ultra/audit.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_cli,node_orchestrator,node_intent,node_user,node_telegram_user toneBlue
class node_research_agent,node_market_agent,node_engineering,node_architect,node_coder,node_reviewer,node_debugger,node_tester,node_evaluator,node_deployer,node_trainer toneAmber
class node_provider_pool,node_task_manager,node_runtime_engine,node_tool_registry,node_memory,node_vectors,node_event_bus,node_policy,node_watchers,node_goals toneMint
class node_telegram,node_ollama,node_web_research,node_tools,node_mcp,node_notifications toneRose
class node_security,node_audit toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/coder1317/aria/blob/master/ultra/cli.py): `ultra/cli.py`
- [Brain orchestrator](https://github.com/coder1317/aria/blob/master/ultra/orchestrator.py): `ultra/orchestrator.py`
- [Intent routing](https://github.com/coder1317/aria/blob/master/ultra/intent.py): `ultra/intent.py`

### Agent workflows

- [Research agent](https://github.com/coder1317/aria/blob/master/ultra/agents/research.py): `ultra/agents/research.py`
- [Market agent](https://github.com/coder1317/aria/blob/master/ultra/agents/market.py): `ultra/agents/market.py`
- [Engineering pipeline](https://github.com/coder1317/aria/blob/master/ultra/agents/engineering.py): `ultra/agents/engineering.py`
- [Architecture planning](https://github.com/coder1317/aria/blob/master/ultra/agents/architect.py): `ultra/agents/architect.py`
- [Code generation](https://github.com/coder1317/aria/blob/master/ultra/agents/coder.py): `ultra/agents/coder.py`
- [Code review](https://github.com/coder1317/aria/blob/master/ultra/agents/reviewer.py): `ultra/agents/reviewer.py`
- [Issue repair](https://github.com/coder1317/aria/blob/master/ultra/agents/debugger.py): `ultra/agents/debugger.py`
- [Test execution](https://github.com/coder1317/aria/blob/master/ultra/agents/tester.py): `ultra/agents/tester.py`
- [Build evaluation](https://github.com/coder1317/aria/blob/master/ultra/evaluator.py): `ultra/evaluator.py`
- [Deployment generation](https://github.com/coder1317/aria/blob/master/ultra/agents/deployer.py): `ultra/agents/deployer.py`
- [Skill extraction](https://github.com/coder1317/aria/blob/master/ultra/agents/trainer.py): `ultra/agents/trainer.py`

### Runtime and memory

- [Provider pool](https://github.com/coder1317/aria/blob/master/ultra/provider_pool.py): `ultra/provider_pool.py`
- [Background task queue](https://github.com/coder1317/aria/blob/master/ultra/task_manager.py): `ultra/task_manager.py`
- [Plan-act runtime](https://github.com/coder1317/aria/blob/master/ultra/core/runtime.py): `ultra/core/runtime.py`
- [Tool registry](https://github.com/coder1317/aria/blob/master/ultra/core/tool_registry.py): `ultra/core/tool_registry.py`
- [Memory and skills](https://github.com/coder1317/aria/blob/master/ultra/core/memory.py): `ultra/core/memory.py`
- [Vector store](https://github.com/coder1317/aria/blob/master/ultra/core/vectors.py): `ultra/core/vectors.py`
- [Event bus](https://github.com/coder1317/aria/blob/master/ultra/core/events.py): `ultra/core/events.py`
- [Event policies](https://github.com/coder1317/aria/blob/master/ultra/core/policy_engine.py): `ultra/core/policy_engine.py`
- [File watchers](https://github.com/coder1317/aria/blob/master/ultra/core/watchers.py): `ultra/core/watchers.py`
- [Goal manager](https://github.com/coder1317/aria/blob/master/ultra/core/goals.py): `ultra/core/goals.py`

### Channels and integrations

- [Telegram adapter](https://github.com/coder1317/aria/blob/master/ultra/channels/telegram.py): `ultra/channels/telegram.py`
- [Local Ollama](https://github.com/coder1317/aria/blob/master/ultra/llm.py): `ultra/llm.py`
- [Web search and fetch](https://github.com/coder1317/aria/blob/master/ultra/tools/researcher.py): `ultra/tools/researcher.py`
- [Built-in tools](https://github.com/coder1317/aria/tree/master/ultra/tools): `ultra/tools`
- [MCP client](https://github.com/coder1317/aria/blob/master/ultra/tools/mcp_client.py): `ultra/tools/mcp_client.py`
- [Notifications](https://github.com/coder1317/aria/blob/master/ultra/core/notifications.py): `ultra/core/notifications.py`

### Security and operations

- [Security scanning](https://github.com/coder1317/aria/blob/master/ultra/security.py): `ultra/security.py`
- [Audit log](https://github.com/coder1317/aria/blob/master/ultra/audit.py): `ultra/audit.py`

### Other components

- **Terminal user**
- **Telegram user**

## Connections

- Terminal user → CLI: submits request
- Telegram user → Telegram adapter: sends message
- Telegram adapter → Brain orchestrator: dispatches message
- CLI → Brain orchestrator: dispatches request
- Brain orchestrator → Intent routing: classifies intent
- Brain orchestrator → Provider pool: requests model work
- Provider pool → Local Ollama: routes locally
- Brain orchestrator → Research agent: dispatches research
- Research agent → Web search and fetch: searches and fetches
- Research agent → Provider pool: synthesizes report
- Brain orchestrator → Market agent: dispatches analysis
- Brain orchestrator → Engineering pipeline: starts build
- Engineering pipeline → Architecture planning: plans project
- Engineering pipeline → Code generation: generates files
- Engineering pipeline → Code review: reviews code
- Engineering pipeline → Security scanning: scans generated code
- Engineering pipeline → Issue repair: repairs issues
- Engineering pipeline → Test execution: runs tests
- Brain orchestrator → Build evaluation: scores build
- Brain orchestrator → Deployment generation: dispatches deployment
- Brain orchestrator → Skill extraction: extracts skills
- Brain orchestrator → Background task queue: submits background work
- Background task queue → Brain orchestrator: runs registered handlers
- Brain orchestrator → Plan-act runtime: creates and runs plan
- Plan-act runtime → Tool registry: executes tool calls
- Tool registry → Built-in tools: dispatches tools
- Tool registry → MCP client: invokes external tools
- Brain orchestrator → Memory and skills: reads and updates
- Brain orchestrator → Vector store: uses embeddings
- File watchers → Event bus: emits file events
- Event bus → Event policies: dispatches events
- Event policies → Background task queue: submits event tasks
- Event policies → Notifications: sends alerts
- Goal manager → Event bus: publishes goal events
- Brain orchestrator → Audit log: records operations
- Brain orchestrator → Notifications: sends updates