# marksman8/hyper architecture

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

- Interactive diagram: https://gitdiagram.com/marksman8/hyper
- Repository: https://github.com/marksman8/hyper

## Overview

AURA is a local-first, model-agnostic personal assistant runtime. A user speaks or sends a task through a client; the authenticated API hands conversation turns to the orchestrator, which generates a response, persists conversation and memory, and can invoke permission-gated tools. Optional branches add voice, screen perception, desktop presence, evaluation, and human-gated configuration evolution. The README documents these capabilities; connections for unsampled subsystems are shown only where that documentation or the source index supports them.

Main entry points: [`src/aura/core/orchestrator.py`](https://github.com/marksman8/hyper/blob/main/src/aura/core/orchestrator.py) (Turn orchestrator), [`src/aura/api/app.py`](https://github.com/marksman8/hyper/blob/main/src/aura/api/app.py) (Local API), [`src/aura/voice/session.py`](https://github.com/marksman8/hyper/blob/main/src/aura/voice/session.py) (Voice session), [`src/aura/core/emitter.py`](https://github.com/marksman8/hyper/blob/main/src/aura/core/emitter.py) (Event bus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and API"]
  node_cli["CLI clients<br/>[cli.py]"]
  node_api["Local API<br/>[app.py]"]
end

subgraph group_reasoning["Conversation runtime"]
  node_orchestrator["Turn orchestrator<br/>[orchestrator.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_provider["Model providers<br/>[openai_compat.py]"]
  node_tools["Tool execution<br/>[runner.py]"]
  node_events["Event bus<br/>[emitter.py]"]
end

subgraph group_state["Memory and security"]
  node_memory[("Persistent memory<br/>[store.py]")]
  node_extraction["Fact extraction<br/>[extraction.py]"]
  node_security["Access and approvals<br/>[permissions.py]"]
  node_audit["Audit trail<br/>[audit.py]"]
end

subgraph group_interaction["Voice and perception"]
  node_voice["Voice session<br/>[session.py]"]
  node_audio["Audio capture<br/>[capture.py]"]
  node_vad["Voice activity<br/>[vad.py]"]
  node_coreclient["Core HTTP client<br/>[core_client.py]"]
  node_vision["Screen perception<br/>[service.py]"]
  node_presence["Desktop presence<br/>[app.py]"]
end

subgraph group_extensions["Evaluation and evolution"]
  node_evaluation["Evaluation harness<br/>[runner.py]"]
  node_comparison["Result comparison<br/>[compare.py]"]
  node_evolution["Config evolution<br/>[search.py]"]
  node_automation["n8n integration<br/>[n8n.py]"]
end

node_user(("User"))
node_model{{"Local model server"}}

node_user -->|"requests tasks"| node_cli
node_cli -->|"calls API"| node_api
node_user -->|"speaks"| node_voice
node_voice -->|"captures audio"| node_audio
node_voice -->|"detects speech"| node_vad
node_voice -->|"requests replies"| node_coreclient
node_coreclient -->|"streams chat over HTTP"| node_api
node_api -->|"routes turns"| node_orchestrator
node_orchestrator -->|"generates responses"| node_provider
node_provider -->|"uses model server"| node_model
node_orchestrator -->|"runs bounded loop"| node_agent
node_agent -.->|"executes selected tools"| node_tools
node_tools -.->|"checks permissions"| node_security
node_orchestrator -->|"loads and persists turns"| node_memory
node_orchestrator -->|"learns facts"| node_extraction
node_orchestrator -->|"records actions"| node_audit
node_api -->|"authenticates requests"| node_security
node_api -->|"serves session views"| node_memory
node_api -->|"publishes events"| node_events
node_vision -->|"emits privacy state"| node_events
node_events -->|"updates display"| node_presence
node_evaluation -.->|"scores results"| node_comparison
node_evolution -->|"compares candidates"| node_comparison
node_automation -.->|"supports integrations"| node_user

click node_cli "https://github.com/marksman8/hyper/blob/main/src/aura/clients/cli.py"
click node_api "https://github.com/marksman8/hyper/blob/main/src/aura/api/app.py"
click node_voice "https://github.com/marksman8/hyper/blob/main/src/aura/voice/session.py"
click node_audio "https://github.com/marksman8/hyper/blob/main/src/aura/voice/audio/capture.py"
click node_vad "https://github.com/marksman8/hyper/blob/main/src/aura/voice/vad.py"
click node_coreclient "https://github.com/marksman8/hyper/blob/main/src/aura/voice/core_client.py"
click node_orchestrator "https://github.com/marksman8/hyper/blob/main/src/aura/core/orchestrator.py"
click node_agent "https://github.com/marksman8/hyper/blob/main/src/aura/core/agent.py"
click node_provider "https://github.com/marksman8/hyper/blob/main/src/aura/models/providers/openai_compat.py"
click node_tools "https://github.com/marksman8/hyper/blob/main/src/aura/tools/runner.py"
click node_memory "https://github.com/marksman8/hyper/blob/main/src/aura/memory/store.py"
click node_extraction "https://github.com/marksman8/hyper/blob/main/src/aura/memory/extraction.py"
click node_security "https://github.com/marksman8/hyper/blob/main/src/aura/security/permissions.py"
click node_audit "https://github.com/marksman8/hyper/blob/main/src/aura/security/audit.py"
click node_vision "https://github.com/marksman8/hyper/blob/main/src/aura/vision/service.py"
click node_presence "https://github.com/marksman8/hyper/blob/main/src/aura/presence/app.py"
click node_events "https://github.com/marksman8/hyper/blob/main/src/aura/core/emitter.py"
click node_evaluation "https://github.com/marksman8/hyper/blob/main/src/aura/eval/runner.py"
click node_comparison "https://github.com/marksman8/hyper/blob/main/src/aura/eval/compare.py"
click node_evolution "https://github.com/marksman8/hyper/blob/main/src/aura/evolution/search.py"
click node_automation "https://github.com/marksman8/hyper/blob/main/src/aura/automation/n8n.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_api,node_user toneBlue
class node_orchestrator,node_agent,node_provider,node_tools,node_events toneAmber
class node_memory,node_extraction,node_security,node_audit,node_model toneMint
class node_voice,node_audio,node_vad,node_coreclient,node_vision,node_presence toneRose
class node_evaluation,node_comparison,node_evolution,node_automation toneIndigo
```

## Components

### Clients and API

- [CLI clients](https://github.com/marksman8/hyper/blob/main/src/aura/clients/cli.py): `src/aura/clients/cli.py`
- [Local API](https://github.com/marksman8/hyper/blob/main/src/aura/api/app.py): `src/aura/api/app.py`

### Conversation runtime

- [Turn orchestrator](https://github.com/marksman8/hyper/blob/main/src/aura/core/orchestrator.py): `src/aura/core/orchestrator.py`
- [Agent loop](https://github.com/marksman8/hyper/blob/main/src/aura/core/agent.py): `src/aura/core/agent.py`
- [Model providers](https://github.com/marksman8/hyper/blob/main/src/aura/models/providers/openai_compat.py): `src/aura/models/providers/openai_compat.py`
- [Tool execution](https://github.com/marksman8/hyper/blob/main/src/aura/tools/runner.py): `src/aura/tools/runner.py`
- [Event bus](https://github.com/marksman8/hyper/blob/main/src/aura/core/emitter.py): `src/aura/core/emitter.py`

### Memory and security

- [Persistent memory](https://github.com/marksman8/hyper/blob/main/src/aura/memory/store.py): `src/aura/memory/store.py`
- [Fact extraction](https://github.com/marksman8/hyper/blob/main/src/aura/memory/extraction.py): `src/aura/memory/extraction.py`
- [Access and approvals](https://github.com/marksman8/hyper/blob/main/src/aura/security/permissions.py): `src/aura/security/permissions.py`
- [Audit trail](https://github.com/marksman8/hyper/blob/main/src/aura/security/audit.py): `src/aura/security/audit.py`

### Voice and perception

- [Voice session](https://github.com/marksman8/hyper/blob/main/src/aura/voice/session.py): `src/aura/voice/session.py`
- [Audio capture](https://github.com/marksman8/hyper/blob/main/src/aura/voice/audio/capture.py): `src/aura/voice/audio/capture.py`
- [Voice activity](https://github.com/marksman8/hyper/blob/main/src/aura/voice/vad.py): `src/aura/voice/vad.py`
- [Core HTTP client](https://github.com/marksman8/hyper/blob/main/src/aura/voice/core_client.py): `src/aura/voice/core_client.py`
- [Screen perception](https://github.com/marksman8/hyper/blob/main/src/aura/vision/service.py): `src/aura/vision/service.py`
- [Desktop presence](https://github.com/marksman8/hyper/blob/main/src/aura/presence/app.py): `src/aura/presence/app.py`

### Evaluation and evolution

- [Evaluation harness](https://github.com/marksman8/hyper/blob/main/src/aura/eval/runner.py): `src/aura/eval/runner.py`
- [Result comparison](https://github.com/marksman8/hyper/blob/main/src/aura/eval/compare.py): `src/aura/eval/compare.py`
- [Config evolution](https://github.com/marksman8/hyper/blob/main/src/aura/evolution/search.py): `src/aura/evolution/search.py`
- [n8n integration](https://github.com/marksman8/hyper/blob/main/src/aura/automation/n8n.py): `src/aura/automation/n8n.py`

### Other components

- **User**
- **Local model server**

## Connections

- User → CLI clients: requests tasks (evidence: `README.md`)
- CLI clients → Local API: calls API (evidence: `README.md`)
- User → Voice session: speaks (evidence: `README.md`)
- Voice session → Audio capture: captures audio (evidence: `src/aura/voice/session.py`)
- Voice session → Voice activity: detects speech (evidence: `src/aura/voice/session.py`)
- Voice session → Core HTTP client: requests replies (evidence: `src/aura/voice/session.py`)
- Core HTTP client → Local API: streams chat over HTTP (evidence: `src/aura/voice/core_client.py`)
- Local API → Turn orchestrator: routes turns (evidence: `src/aura/api/app.py`)
- Turn orchestrator → Model providers: generates responses (evidence: `src/aura/core/orchestrator.py`)
- Model providers → Local model server: uses model server (evidence: `README.md`)
- Turn orchestrator → Agent loop: runs bounded loop (evidence: `src/aura/core/orchestrator.py`)
- Agent loop → Tool execution: executes selected tools (evidence: `README.md`)
- Tool execution → Access and approvals: checks permissions (evidence: `README.md`)
- Turn orchestrator → Persistent memory: loads and persists turns (evidence: `src/aura/core/orchestrator.py`)
- Turn orchestrator → Fact extraction: learns facts (evidence: `src/aura/core/orchestrator.py`)
- Turn orchestrator → Audit trail: records actions (evidence: `src/aura/core/orchestrator.py`)
- Local API → Access and approvals: authenticates requests (evidence: `src/aura/api/app.py`)
- Local API → Persistent memory: serves session views (evidence: `src/aura/api/app.py`)
- Local API → Event bus: publishes events (evidence: `src/aura/api/app.py`)
- Screen perception → Event bus: emits privacy state (evidence: `src/aura/vision/service.py`)
- Event bus → Desktop presence: updates display (evidence: `src/aura/presence/app.py`)
- Evaluation harness → Result comparison: scores results (evidence: `src/aura/clients/eval_cli.py`)
- Config evolution → Result comparison: compares candidates (evidence: `src/aura/evolution/search.py`)
- n8n integration → User: supports integrations