# 3yearszhuang/aervox-harness architecture

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

- Interactive diagram: https://gitdiagram.com/3yearszhuang/aervox-harness
- Repository: https://github.com/3yearszhuang/aervox-harness
- Video tour (about a minute): https://gitdiagram.com/3yearszhuang/aervox-harness/video

## Overview

Aervox is a local-first personal assistant spanning desktop, web, and CLI entry points. The principal workflow is a user turn entering the local API, being accepted and executed by the companion conversation runtime, and producing a streamed response; configured model and tools support that work, while local SQLite holds records. Separate capabilities cover memory and diary, proactive reminders, learning/review, and extensibility. The graph also shows core tool-safety layers. Some subsystem links are documented only at product level; unsampled implementation details are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/api/src/app.ts) (Local API), [`packages/host-runtime/src/modules/companion/conversation/execution.ts`](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/companion/conversation/execution.ts) (Turn execution), [`apps/worker/src/worker-host.ts`](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/worker/src/worker-host.ts) (Background worker), [`packages/host-runtime/src/modules/ecosystem/tools`](https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/ecosystem/tools) (Tools and plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_surfaces["Desktop and web<br/>[App.vue]"]
  node_cli["CLI<br/>[cli.ts]"]
  node_client["API transport<br/>[transport.ts]"]
end

subgraph group_runtime["Assistant runtime"]
  node_api["Local API<br/>[app.ts]"]
  node_conversation["Conversation routes<br/>[routes.ts]"]
  node_turn["Turn execution<br/>[execution.ts]"]
  node_worker["Background worker<br/>[worker-host.ts]"]
end

subgraph group_data["Local data"]
  node_db[("SQLite records<br/>[client.ts]")]
end

subgraph group_capabilities["Product capabilities"]
  node_tools["Tools and plugins"]
  node_memory["Memory and recall"]
  node_diary["Diary generation"]
  node_proactive["Proactive assistance<br/>[routes.ts]"]
  node_rules["Proactive rules<br/>[rule-engine.ts]"]
  node_learning["Learning and review<br/>[routes.ts]"]
  node_extensions["Skills and MCP"]
end

subgraph group_core["Agent core"]
  node_corepipe["Tool execution pipeline<br/>[tool-pipeline.ts]"]
  node_toolguard["Tool validation and safety"]
end

node_user(("User"))
node_model["Configured model service"]

node_user -->|"uses"| node_surfaces
node_user -->|"uses"| node_cli
node_surfaces -->|"connects to"| node_api
node_cli -->|"connects to"| node_api
node_api -.->|"routes requests"| node_conversation
node_conversation -->|"accepts turn"| node_turn
node_turn -->|"requests generation"| node_model
node_turn -->|"invokes tools"| node_tools
node_tools -.->|"executes calls"| node_corepipe
node_corepipe -->|"validates inputs"| node_toolguard
node_api -->|"persists records"| node_db
node_worker -->|"processes scheduled work"| node_db
node_turn -.->|"uses memory"| node_memory
node_worker -.->|"generates diary"| node_diary
node_worker -.->|"evaluates triggers"| node_rules
node_proactive -.->|"exposes controls"| node_rules
node_api -.->|"serves learning"| node_learning
node_tools -.->|"supports extensions"| node_extensions

click node_surfaces "https://github.com/3yearszhuang/aervox-harness/blob/main/apps/desktop/src/renderer/src/App.vue"
click node_cli "https://github.com/3yearszhuang/aervox-harness/blob/main/apps/cli/src/cli.ts"
click node_api "https://github.com/3yearszhuang/aervox-harness/blob/main/apps/api/src/app.ts"
click node_conversation "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/companion/conversation/routes.ts"
click node_turn "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/companion/conversation/execution.ts"
click node_client "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/api-client/src/transport.ts"
click node_tools "https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/ecosystem/tools"
click node_corepipe "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/core/src/tool-pipeline.ts"
click node_toolguard "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/core/src/host-tool-runtime.ts"
click node_db "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/repositories/src/client.ts"
click node_memory "https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/companion/memory"
click node_worker "https://github.com/3yearszhuang/aervox-harness/blob/main/apps/worker/src/worker-host.ts"
click node_proactive "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/proactive/proactive/routes.ts"
click node_rules "https://github.com/3yearszhuang/aervox-harness/blob/main/apps/worker/src/proactive/rule-engine.ts"
click node_learning "https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/learning/learning/routes.ts"
click node_extensions "https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/ecosystem"

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_surfaces,node_cli,node_client,node_user toneBlue
class node_api,node_conversation,node_turn,node_worker toneAmber
class node_db toneMint
class node_tools,node_memory,node_diary,node_proactive,node_rules,node_learning,node_extensions toneRose
class node_corepipe,node_toolguard,node_model toneIndigo
```

## Components

### User interfaces

- [Desktop and web](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/desktop/src/renderer/src/App.vue): `apps/desktop/src/renderer/src/App.vue`
- [CLI](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/cli/src/cli.ts): `apps/cli/src/cli.ts`
- [API transport](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/api-client/src/transport.ts): `packages/api-client/src/transport.ts`

### Assistant runtime

- [Local API](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Conversation routes](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/companion/conversation/routes.ts): `packages/host-runtime/src/modules/companion/conversation/routes.ts`
- [Turn execution](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/companion/conversation/execution.ts): `packages/host-runtime/src/modules/companion/conversation/execution.ts`
- [Background worker](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/worker/src/worker-host.ts): `apps/worker/src/worker-host.ts`

### Local data

- [SQLite records](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/repositories/src/client.ts): `packages/repositories/src/client.ts`

### Product capabilities

- [Tools and plugins](https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/ecosystem/tools): `packages/host-runtime/src/modules/ecosystem/tools`
- [Memory and recall](https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/companion/memory): `packages/host-runtime/src/modules/companion/memory`
- **Diary generation**
- [Proactive assistance](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/proactive/proactive/routes.ts): `packages/host-runtime/src/modules/proactive/proactive/routes.ts`
- [Proactive rules](https://github.com/3yearszhuang/aervox-harness/blob/main/apps/worker/src/proactive/rule-engine.ts): `apps/worker/src/proactive/rule-engine.ts`
- [Learning and review](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/host-runtime/src/modules/learning/learning/routes.ts): `packages/host-runtime/src/modules/learning/learning/routes.ts`
- [Skills and MCP](https://github.com/3yearszhuang/aervox-harness/tree/main/packages/host-runtime/src/modules/ecosystem): `packages/host-runtime/src/modules/ecosystem`

### Agent core

- [Tool execution pipeline](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/core/src/tool-pipeline.ts): `packages/core/src/tool-pipeline.ts`
- [Tool validation and safety](https://github.com/3yearszhuang/aervox-harness/blob/main/packages/core/src/host-tool-runtime.ts): `packages/core/src/host-tool-runtime.ts`

### Other components

- **User**
- **Configured model service**

## Connections

- User → Desktop and web: uses (evidence: `README.md`)
- User → CLI: uses (evidence: `README.md`)
- Desktop and web → Local API: connects to (evidence: `README.md`)
- CLI → Local API: connects to (evidence: `README.md`)
- Local API → Conversation routes: routes requests
- Conversation routes → Turn execution: accepts turn (evidence: `packages/host-runtime/src/modules/companion/conversation/routes.ts`)
- Turn execution → Configured model service: requests generation (evidence: `README.md`)
- Turn execution → Tools and plugins: invokes tools (evidence: `README.md`)
- Tools and plugins → Tool execution pipeline: executes calls
- Tool execution pipeline → Tool validation and safety: validates inputs (evidence: `packages/core/src/tool-pipeline.ts`)
- Local API → SQLite records: persists records (evidence: `README.md`)
- Background worker → SQLite records: processes scheduled work (evidence: `README.md`)
- Turn execution → Memory and recall: uses memory
- Background worker → Diary generation: generates diary
- Background worker → Proactive rules: evaluates triggers
- Proactive assistance → Proactive rules: exposes controls
- Local API → Learning and review: serves learning
- Tools and plugins → Skills and MCP: supports extensions