# manish-kuntal/altros-ai architecture

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

- Interactive diagram: https://gitdiagram.com/manish-kuntal/altros-ai
- Repository: https://github.com/manish-kuntal/altros-ai

## Overview

ALTROS is a local-first personal assistant: users speak or type requests, which are routed to an LLM, knowledge retrieval, or action modules; responses return through the CLI, voice, or web server. Its major documented branches include persistent memory, PDF/RAG learning, web search, desktop and browser automation, scheduled autonomy, and communication integrations. The excerpts show core routing, brain, memory, and server behavior; several feature connections are documented in the README rather than verified in sampled implementation.

Main entry points: [`main.py`](https://github.com/manish-kuntal/altros-ai/blob/main/main.py) (Application Entry), [`core/router.py`](https://github.com/manish-kuntal/altros-ai/blob/main/core/router.py) (Request Router), [`core/brain.py`](https://github.com/manish-kuntal/altros-ai/blob/main/core/brain.py) (LLM Brain), [`core/memory.py`](https://github.com/manish-kuntal/altros-ai/blob/main/core/memory.py) (Persistent Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_main["Application Entry<br/>[main.py]"]
  node_voice["Voice I/O<br/>[voice.py]"]
  node_wake["Wake Word<br/>[wake_word.py]"]
  node_server["Web API<br/>[server.py]"]
end

subgraph group_intelligence["Reasoning and Knowledge"]
  node_router["Request Router<br/>[router.py]"]
  node_brain["LLM Brain<br/>[brain.py]"]
  node_thinking["Thinking Engine<br/>[thinking.py]"]
  node_memory[("Persistent Memory<br/>[memory.py]")]
  node_knowledge["RAG Knowledge<br/>[knowledge.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
end

subgraph group_automation["Automation and Control"]
  node_pc["PC Control<br/>[pc_control.py]"]
  node_browser["Browser Control<br/>[browser_control.py]"]
  node_system["System Control<br/>[system_control.py]"]
  node_terminal["Terminal Control"]
  node_autonomy["Autonomous Tasks<br/>[autonomy.py]"]
  node_scheduler["Task Scheduler<br/>[scheduler.py]"]
  node_events["Event Watcher<br/>[event_watcher.py]"]
  node_permissions["Action Permissions<br/>[permissions.py]"]
  node_actionlog[("Action Log<br/>[action_logger.py]")]
end

subgraph group_integrations["External Integrations"]
  node_ollama{{"Ollama Runtime"}}
  node_internet["Web Search<br/>[internet.py]"]
  node_gmail["Gmail Workflows<br/>[gmail.py]"]
  node_instagram["Instagram Workflows<br/>[instagram.py]"]
  node_whatsapp["WhatsApp Bridge<br/>[whatsapp.py]"]
  node_bridge{{"WhatsApp Service<br/>[whatsapp_bridge.js]"}}
end

node_user(("User"))

node_user -->|"submits request"| node_main
node_main -->|"routes requests"| node_router
node_main -->|"starts voice"| node_voice
node_main -->|"enables activation"| node_wake
node_main -->|"starts server"| node_server
node_main -->|"initializes"| node_memory
node_main -->|"initializes"| node_brain
node_main -->|"initializes"| node_thinking
node_main -->|"registers feature"| node_knowledge
node_main -->|"registers feature"| node_internet
node_main -->|"registers feature"| node_pc
node_main -->|"registers feature"| node_autonomy
node_main -->|"registers feature"| node_gmail
node_main -->|"registers feature"| node_instagram
node_router -->|"generates response"| node_brain
node_router -->|"reads context"| node_memory
node_router -->|"passes retrieved context"| node_knowledge
node_router -->|"passes search context"| node_internet
node_router -->|"dispatches action"| node_pc
node_router -->|"dispatches action"| node_autonomy
node_brain -->|"reads history"| node_memory
node_brain -->|"requests intent plan"| node_thinking
node_brain -->|"sends prompt"| node_ollama
node_server -->|"routes chat"| node_router
node_server -->|"reads and stores"| node_memory
node_voice -->|"submits transcript"| node_router
node_voice -->|"speaks response"| node_user
node_knowledge -.->|"indexes knowledge"| node_memory
node_autonomy -.->|"schedules tasks"| node_scheduler
node_events -->|"logs actions"| node_actionlog
node_browser -->|"logs actions"| node_actionlog
node_scheduler -->|"logs actions"| node_actionlog
node_system -->|"checks permissions"| node_permissions
node_terminal -->|"checks permissions"| node_permissions
node_whatsapp -->|"checks permissions"| node_permissions
node_whatsapp -.->|"communicates with"| node_bridge
node_config -->|"configures model"| node_brain
node_config -->|"configures storage"| node_memory
node_config -->|"configures endpoint"| node_server

click node_main "https://github.com/manish-kuntal/altros-ai/blob/main/main.py"
click node_voice "https://github.com/manish-kuntal/altros-ai/blob/main/modules/voice.py"
click node_wake "https://github.com/manish-kuntal/altros-ai/blob/main/modules/wake_word.py"
click node_server "https://github.com/manish-kuntal/altros-ai/blob/main/modules/server.py"
click node_router "https://github.com/manish-kuntal/altros-ai/blob/main/core/router.py"
click node_brain "https://github.com/manish-kuntal/altros-ai/blob/main/core/brain.py"
click node_thinking "https://github.com/manish-kuntal/altros-ai/blob/main/core/thinking.py"
click node_memory "https://github.com/manish-kuntal/altros-ai/blob/main/core/memory.py"
click node_knowledge "https://github.com/manish-kuntal/altros-ai/blob/main/modules/knowledge.py"
click node_internet "https://github.com/manish-kuntal/altros-ai/blob/main/modules/internet.py"
click node_pc "https://github.com/manish-kuntal/altros-ai/blob/main/modules/pc_control.py"
click node_browser "https://github.com/manish-kuntal/altros-ai/blob/main/modules/browser_control.py"
click node_system "https://github.com/manish-kuntal/altros-ai/blob/main/modules/system_control.py"
click node_terminal "https://github.com/manish-kuntal/altros-ai/blob/main/modules/terminal_control.py"
click node_autonomy "https://github.com/manish-kuntal/altros-ai/blob/main/modules/autonomy.py"
click node_scheduler "https://github.com/manish-kuntal/altros-ai/blob/main/modules/scheduler.py"
click node_events "https://github.com/manish-kuntal/altros-ai/blob/main/modules/event_watcher.py"
click node_permissions "https://github.com/manish-kuntal/altros-ai/blob/main/core/permissions.py"
click node_actionlog "https://github.com/manish-kuntal/altros-ai/blob/main/core/action_logger.py"
click node_gmail "https://github.com/manish-kuntal/altros-ai/blob/main/modules/gmail.py"
click node_instagram "https://github.com/manish-kuntal/altros-ai/blob/main/modules/instagram.py"
click node_whatsapp "https://github.com/manish-kuntal/altros-ai/blob/main/modules/whatsapp.py"
click node_bridge "https://github.com/manish-kuntal/altros-ai/blob/main/whatsapp/whatsapp_bridge.js"
click node_config "https://github.com/manish-kuntal/altros-ai/blob/main/config.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_main,node_voice,node_wake,node_server,node_user toneBlue
class node_router,node_brain,node_thinking,node_memory,node_knowledge,node_config toneAmber
class node_pc,node_browser,node_system,node_terminal,node_autonomy,node_scheduler,node_events,node_permissions,node_actionlog toneMint
class node_ollama,node_internet,node_gmail,node_instagram,node_whatsapp,node_bridge toneRose
```

## Components

### User Interaction

- [Application Entry](https://github.com/manish-kuntal/altros-ai/blob/main/main.py): `main.py`
- [Voice I/O](https://github.com/manish-kuntal/altros-ai/blob/main/modules/voice.py): `modules/voice.py`
- [Wake Word](https://github.com/manish-kuntal/altros-ai/blob/main/modules/wake_word.py): `modules/wake_word.py`
- [Web API](https://github.com/manish-kuntal/altros-ai/blob/main/modules/server.py): `modules/server.py`

### Reasoning and Knowledge

- [Request Router](https://github.com/manish-kuntal/altros-ai/blob/main/core/router.py): `core/router.py`
- [LLM Brain](https://github.com/manish-kuntal/altros-ai/blob/main/core/brain.py): `core/brain.py`
- [Thinking Engine](https://github.com/manish-kuntal/altros-ai/blob/main/core/thinking.py): `core/thinking.py`
- [Persistent Memory](https://github.com/manish-kuntal/altros-ai/blob/main/core/memory.py): `core/memory.py`
- [RAG Knowledge](https://github.com/manish-kuntal/altros-ai/blob/main/modules/knowledge.py): `modules/knowledge.py`
- [Runtime Configuration](https://github.com/manish-kuntal/altros-ai/blob/main/config.py): `config.py`

### Automation and Control

- [PC Control](https://github.com/manish-kuntal/altros-ai/blob/main/modules/pc_control.py): `modules/pc_control.py`
- [Browser Control](https://github.com/manish-kuntal/altros-ai/blob/main/modules/browser_control.py): `modules/browser_control.py`
- [System Control](https://github.com/manish-kuntal/altros-ai/blob/main/modules/system_control.py): `modules/system_control.py`
- [Terminal Control](https://github.com/manish-kuntal/altros-ai/blob/main/modules/terminal_control.py): `modules/terminal_control.py`
- [Autonomous Tasks](https://github.com/manish-kuntal/altros-ai/blob/main/modules/autonomy.py): `modules/autonomy.py`
- [Task Scheduler](https://github.com/manish-kuntal/altros-ai/blob/main/modules/scheduler.py): `modules/scheduler.py`
- [Event Watcher](https://github.com/manish-kuntal/altros-ai/blob/main/modules/event_watcher.py): `modules/event_watcher.py`
- [Action Permissions](https://github.com/manish-kuntal/altros-ai/blob/main/core/permissions.py): `core/permissions.py`
- [Action Log](https://github.com/manish-kuntal/altros-ai/blob/main/core/action_logger.py): `core/action_logger.py`

### External Integrations

- **Ollama Runtime**
- [Web Search](https://github.com/manish-kuntal/altros-ai/blob/main/modules/internet.py): `modules/internet.py`
- [Gmail Workflows](https://github.com/manish-kuntal/altros-ai/blob/main/modules/gmail.py): `modules/gmail.py`
- [Instagram Workflows](https://github.com/manish-kuntal/altros-ai/blob/main/modules/instagram.py): `modules/instagram.py`
- [WhatsApp Bridge](https://github.com/manish-kuntal/altros-ai/blob/main/modules/whatsapp.py): `modules/whatsapp.py`
- [WhatsApp Service](https://github.com/manish-kuntal/altros-ai/blob/main/whatsapp/whatsapp_bridge.js): `whatsapp/whatsapp_bridge.js`

### Other components

- **User**

## Connections

- User → Application Entry: submits request (evidence: `README.md`)
- Application Entry → Request Router: routes requests (evidence: `main.py`)
- Application Entry → Voice I/O: starts voice (evidence: `main.py`)
- Application Entry → Wake Word: enables activation (evidence: `main.py`)
- Application Entry → Web API: starts server (evidence: `main.py`)
- Application Entry → Persistent Memory: initializes (evidence: `main.py`)
- Application Entry → LLM Brain: initializes (evidence: `main.py`)
- Application Entry → Thinking Engine: initializes (evidence: `main.py`)
- Application Entry → RAG Knowledge: registers feature (evidence: `main.py`)
- Application Entry → Web Search: registers feature (evidence: `main.py`)
- Application Entry → PC Control: registers feature (evidence: `main.py`)
- Application Entry → Autonomous Tasks: registers feature (evidence: `main.py`)
- Application Entry → Gmail Workflows: registers feature (evidence: `main.py`)
- Application Entry → Instagram Workflows: registers feature (evidence: `main.py`)
- Request Router → LLM Brain: generates response (evidence: `core/router.py`)
- Request Router → Persistent Memory: reads context (evidence: `core/router.py`)
- Request Router → RAG Knowledge: passes retrieved context (evidence: `README.md`)
- Request Router → Web Search: passes search context (evidence: `README.md`)
- Request Router → PC Control: dispatches action (evidence: `core/router.py`)
- Request Router → Autonomous Tasks: dispatches action (evidence: `core/router.py`)
- LLM Brain → Persistent Memory: reads history (evidence: `core/brain.py`)
- LLM Brain → Thinking Engine: requests intent plan (evidence: `core/brain.py`)
- LLM Brain → Ollama Runtime: sends prompt (evidence: `core/brain.py`)
- Web API → Request Router: routes chat (evidence: `modules/server.py`)
- Web API → Persistent Memory: reads and stores (evidence: `modules/server.py`)
- Voice I/O → Request Router: submits transcript (evidence: `modules/voice.py`)
- Voice I/O → User: speaks response (evidence: `modules/voice.py`)
- RAG Knowledge → Persistent Memory: indexes knowledge (evidence: `README.md`)
- Autonomous Tasks → Task Scheduler: schedules tasks (evidence: `README.md`)
- Event Watcher → Action Log: logs actions (evidence: `modules/event_watcher.py`)
- Browser Control → Action Log: logs actions (evidence: `modules/browser_control.py`)
- Task Scheduler → Action Log: logs actions (evidence: `modules/scheduler.py`)
- System Control → Action Permissions: checks permissions (evidence: `modules/system_control.py`)
- Terminal Control → Action Permissions: checks permissions (evidence: `modules/terminal_control.py`)
- WhatsApp Bridge → Action Permissions: checks permissions (evidence: `modules/whatsapp.py`)
- WhatsApp Bridge → WhatsApp Service: communicates with (evidence: `README.md`)
- Runtime Configuration → LLM Brain: configures model (evidence: `core/brain.py`)
- Runtime Configuration → Persistent Memory: configures storage (evidence: `core/memory.py`)
- Runtime Configuration → Web API: configures endpoint (evidence: `modules/server.py`)
