# jackson254365/personal-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/jackson254365/personal-ai-agent
- Repository: https://github.com/jackson254365/personal-ai-agent

## Overview

Personal AI Agent is a locally orchestrated Linux assistant with CLI, REST/WebSocket, messaging, and voice interaction channels. Its principal workflow sends a user request through the reasoning engine, which plans and dispatches registered tools subject to safety checks and approval; results are reflected and actions audited. Distinct capability branches cover finance, communications, desktop/system operations, scheduling, and document intelligence. The README documents several capabilities whose source was not sampled; those are represented without speculative implementation links.

Main entry points: [`src/core/reasoning_engine.py`](https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/reasoning_engine.py) (Reasoning Engine), [`src/offline/autonomy_engine.py`](https://github.com/jackson254365/personal-ai-agent/blob/master/src/offline/autonomy_engine.py) (Offline Autonomy), [`src/system/resource_monitor.py`](https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/resource_monitor.py) (Resource Monitor), [`src/finance/market_ingestion.py`](https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/market_ingestion.py) (Market Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["REST / WebSocket<br/>[server.py]"]
  node_whatsapp["WhatsApp Bridge<br/>[whatsapp_bridge.py]"]
  node_sip["SIP Pipeline<br/>[sip_pipeline.py]"]
end

subgraph group_core["Agent Core"]
  node_reasoning["Reasoning Engine"]
  node_registry["Tool Registry<br/>[tool_registry.py]"]
  node_safety["Safety Gatekeeper"]
  node_eventbus["Priority Event Bus<br/>[event_bus.py]"]
  node_audit[("Audit Trail<br/>[canonical_log.py]")]
  node_merkle["Merkle Chain<br/>[merkle_chain.py]"]
end

subgraph group_finance["Finance"]
  node_market["Market Ingestion"]
  node_risk["Quant Risk"]
  node_execution["Execution Gateway"]
end

subgraph group_communications["Communications"]
  node_crypto["E2EE Crypto<br/>[crypto_e2ee.py]"]
  node_voiceauth["Voice Biometrics<br/>[voice_auth.py]"]
end

subgraph group_operations["System Capabilities"]
  node_calendar[("Calendar Sync<br/>[calendar_sync.py]")]
  node_desktop["Desktop Adapters"]
  node_terminal["PTY Executor<br/>[pty_executor.py]"]
  node_ocr["OCR Pipeline<br/>[ocr_pipeline.py]"]
  node_media["MPRIS Control<br/>[mpris_control.py]"]
  node_resource["Resource Monitor"]
  node_healing["Self Healing<br/>[self_healing.py]"]
  node_backup["GFS Backup<br/>[gfs_backup.py]"]
  node_network["Connectivity Monitor"]
  node_offline["Offline Autonomy<br/>[autonomy_engine.py]"]
end

node_user(("User"))

node_user -->|"submits command"| node_cli
node_user -->|"submits request"| node_api
node_cli -->|"routes prompt"| node_reasoning
node_api -->|"routes prompt"| node_reasoning
node_whatsapp -->|"forwards messages"| node_reasoning
node_sip -->|"checks caller"| node_voiceauth
node_sip -->|"publishes events"| node_eventbus
node_whatsapp -->|"uses encryption"| node_crypto
node_reasoning -->|"dispatches tools"| node_registry
node_reasoning -->|"records decisions"| node_audit
node_registry -->|"checks permissions"| node_safety
node_market -->|"publishes ticks"| node_eventbus
node_risk -->|"reads orderbook"| node_market
node_execution -->|"validates exposure"| node_risk
node_execution -->|"reads market data"| node_market
node_audit -->|"uses hash chain"| node_merkle
node_resource -.->|"publishes telemetry"| node_eventbus
node_resource -.->|"reports status"| node_network
node_offline -->|"checks connectivity"| node_network
node_offline -->|"falls back"| node_reasoning
node_offline -->|"reads snapshot"| node_resource

click node_cli "https://github.com/jackson254365/personal-ai-agent/blob/master/src/cli.py"
click node_api "https://github.com/jackson254365/personal-ai-agent/blob/master/src/api/server.py"
click node_whatsapp "https://github.com/jackson254365/personal-ai-agent/blob/master/src/messaging/whatsapp_bridge.py"
click node_sip "https://github.com/jackson254365/personal-ai-agent/blob/master/src/telephony/sip_pipeline.py"
click node_reasoning "https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/reasoning_engine.py"
click node_registry "https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/tool_registry.py"
click node_safety "https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/safety_gatekeeper.py"
click node_eventbus "https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/event_bus.py"
click node_audit "https://github.com/jackson254365/personal-ai-agent/blob/master/src/audit/canonical_log.py"
click node_merkle "https://github.com/jackson254365/personal-ai-agent/blob/master/src/audit/merkle_chain.py"
click node_market "https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/market_ingestion.py"
click node_risk "https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/quant_risk_engine.py"
click node_execution "https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/execution_gateway.py"
click node_crypto "https://github.com/jackson254365/personal-ai-agent/blob/master/src/messaging/crypto_e2ee.py"
click node_voiceauth "https://github.com/jackson254365/personal-ai-agent/blob/master/src/telephony/voice_auth.py"
click node_calendar "https://github.com/jackson254365/personal-ai-agent/blob/master/src/calendar/calendar_sync.py"
click node_desktop "https://github.com/jackson254365/personal-ai-agent/blob/master/src/desktop/desktop_adapters.py"
click node_terminal "https://github.com/jackson254365/personal-ai-agent/blob/master/src/terminal/pty_executor.py"
click node_ocr "https://github.com/jackson254365/personal-ai-agent/blob/master/src/idp/ocr_pipeline.py"
click node_media "https://github.com/jackson254365/personal-ai-agent/blob/master/src/media/mpris_control.py"
click node_resource "https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/resource_monitor.py"
click node_healing "https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/self_healing.py"
click node_backup "https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/gfs_backup.py"
click node_network "https://github.com/jackson254365/personal-ai-agent/blob/master/src/network/connectivity_monitor.py"
click node_offline "https://github.com/jackson254365/personal-ai-agent/blob/master/src/offline/autonomy_engine.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_whatsapp,node_sip,node_user toneBlue
class node_reasoning,node_registry,node_safety,node_eventbus,node_audit,node_merkle toneAmber
class node_market,node_risk,node_execution toneMint
class node_crypto,node_voiceauth toneRose
class node_calendar,node_desktop,node_terminal,node_ocr,node_media,node_resource,node_healing,node_backup,node_network,node_offline toneIndigo
```

## Components

### Interaction

- [CLI](https://github.com/jackson254365/personal-ai-agent/blob/master/src/cli.py): `src/cli.py`
- [REST / WebSocket](https://github.com/jackson254365/personal-ai-agent/blob/master/src/api/server.py): `src/api/server.py`
- [WhatsApp Bridge](https://github.com/jackson254365/personal-ai-agent/blob/master/src/messaging/whatsapp_bridge.py): `src/messaging/whatsapp_bridge.py`
- [SIP Pipeline](https://github.com/jackson254365/personal-ai-agent/blob/master/src/telephony/sip_pipeline.py): `src/telephony/sip_pipeline.py`

### Agent Core

- [Reasoning Engine](https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/reasoning_engine.py): `src/core/reasoning_engine.py`
- [Tool Registry](https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/tool_registry.py): `src/core/tool_registry.py`
- [Safety Gatekeeper](https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/safety_gatekeeper.py): `src/core/safety_gatekeeper.py`
- [Priority Event Bus](https://github.com/jackson254365/personal-ai-agent/blob/master/src/core/event_bus.py): `src/core/event_bus.py`
- [Audit Trail](https://github.com/jackson254365/personal-ai-agent/blob/master/src/audit/canonical_log.py): `src/audit/canonical_log.py`
- [Merkle Chain](https://github.com/jackson254365/personal-ai-agent/blob/master/src/audit/merkle_chain.py): `src/audit/merkle_chain.py`

### Finance

- [Market Ingestion](https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/market_ingestion.py): `src/finance/market_ingestion.py`
- [Quant Risk](https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/quant_risk_engine.py): `src/finance/quant_risk_engine.py`
- [Execution Gateway](https://github.com/jackson254365/personal-ai-agent/blob/master/src/finance/execution_gateway.py): `src/finance/execution_gateway.py`

### Communications

- [E2EE Crypto](https://github.com/jackson254365/personal-ai-agent/blob/master/src/messaging/crypto_e2ee.py): `src/messaging/crypto_e2ee.py`
- [Voice Biometrics](https://github.com/jackson254365/personal-ai-agent/blob/master/src/telephony/voice_auth.py): `src/telephony/voice_auth.py`

### System Capabilities

- [Calendar Sync](https://github.com/jackson254365/personal-ai-agent/blob/master/src/calendar/calendar_sync.py): `src/calendar/calendar_sync.py`
- [Desktop Adapters](https://github.com/jackson254365/personal-ai-agent/blob/master/src/desktop/desktop_adapters.py): `src/desktop/desktop_adapters.py`
- [PTY Executor](https://github.com/jackson254365/personal-ai-agent/blob/master/src/terminal/pty_executor.py): `src/terminal/pty_executor.py`
- [OCR Pipeline](https://github.com/jackson254365/personal-ai-agent/blob/master/src/idp/ocr_pipeline.py): `src/idp/ocr_pipeline.py`
- [MPRIS Control](https://github.com/jackson254365/personal-ai-agent/blob/master/src/media/mpris_control.py): `src/media/mpris_control.py`
- [Resource Monitor](https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/resource_monitor.py): `src/system/resource_monitor.py`
- [Self Healing](https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/self_healing.py): `src/system/self_healing.py`
- [GFS Backup](https://github.com/jackson254365/personal-ai-agent/blob/master/src/system/gfs_backup.py): `src/system/gfs_backup.py`
- [Connectivity Monitor](https://github.com/jackson254365/personal-ai-agent/blob/master/src/network/connectivity_monitor.py): `src/network/connectivity_monitor.py`
- [Offline Autonomy](https://github.com/jackson254365/personal-ai-agent/blob/master/src/offline/autonomy_engine.py): `src/offline/autonomy_engine.py`

### Other components

- **User**

## Connections

- User → CLI: submits command (evidence: `README.md`)
- User → REST / WebSocket: submits request (evidence: `README.md`)
- CLI → Reasoning Engine: routes prompt (evidence: `src/cli.py`)
- REST / WebSocket → Reasoning Engine: routes prompt (evidence: `src/api/server.py`)
- WhatsApp Bridge → Reasoning Engine: forwards messages (evidence: `src/messaging/whatsapp_bridge.py`)
- SIP Pipeline → Voice Biometrics: checks caller (evidence: `src/telephony/sip_pipeline.py`)
- SIP Pipeline → Priority Event Bus: publishes events (evidence: `src/telephony/sip_pipeline.py`)
- WhatsApp Bridge → E2EE Crypto: uses encryption (evidence: `src/messaging/whatsapp_bridge.py`)
- Reasoning Engine → Tool Registry: dispatches tools (evidence: `src/core/reasoning_engine.py`)
- Reasoning Engine → Audit Trail: records decisions (evidence: `src/core/reasoning_engine.py`)
- Tool Registry → Safety Gatekeeper: checks permissions (evidence: `src/core/tool_registry.py`)
- Market Ingestion → Priority Event Bus: publishes ticks (evidence: `src/finance/market_ingestion.py`)
- Quant Risk → Market Ingestion: reads orderbook (evidence: `src/finance/quant_risk_engine.py`)
- Execution Gateway → Quant Risk: validates exposure (evidence: `src/finance/execution_gateway.py`)
- Execution Gateway → Market Ingestion: reads market data (evidence: `src/finance/execution_gateway.py`)
- Audit Trail → Merkle Chain: uses hash chain (evidence: `src/audit/canonical_log.py`)
- Resource Monitor → Priority Event Bus: publishes telemetry (evidence: `src/system/resource_monitor.py`)
- Resource Monitor → Connectivity Monitor: reports status
- Offline Autonomy → Connectivity Monitor: checks connectivity (evidence: `src/offline/autonomy_engine.py`)
- Offline Autonomy → Reasoning Engine: falls back (evidence: `src/offline/autonomy_engine.py`)
- Offline Autonomy → Resource Monitor: reads snapshot (evidence: `src/offline/autonomy_engine.py`)
