# titechprabhasolutions/brahma-ai-evo architecture

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

- Interactive diagram: https://gitdiagram.com/titechprabhasolutions/brahma-ai-evo
- Repository: https://github.com/titechprabhasolutions/brahma-ai-evo

## Overview

Brahma AI Evo is a Windows desktop AI environment. The main user journey is a voice or text request entering the desktop application, being interpreted and planned, then dispatched to an action that returns a result to the interface. The repository also includes separate capability branches for self-evolving skills, document work, hardware guidance, smart-home control, and Android device connectivity. Edges use README-documented relationships or visible source-index references; unsampled implementations and uncertain wiring are not expanded.

Main entry points: [`main.py`](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/main.py) (Application Loop), [`agent/executor.py`](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/executor.py) (Action Executor), [`llm_client.py`](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/llm_client.py) (Unified AI Client), [`brahma_connect/gateway/server.py`](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/server.py) (Connect Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Experience"]
  node_main["Application Loop<br/>[main.py]"]
  node_ui["Command UI<br/>[ui.py]"]
  node_dashboard["Local Dashboard<br/>[server.py]"]
end

subgraph group_agent["Agent and Memory"]
  node_planner["Task Planner<br/>[planner.py]"]
  node_executor["Action Executor<br/>[executor.py]"]
  node_task_queue["Task Queue<br/>[task_queue.py]"]
  node_llm["Unified AI Client<br/>[llm_client.py]"]
  node_memory[("Long-Term Memory<br/>[memory_manager.py]")]
  node_local_brain["Local Brain<br/>[local_brain.py]"]
end

subgraph group_actions["Desktop Capabilities"]
  node_file_processor["File Processing<br/>[file_processor.py]"]
  node_computer_settings["System Settings"]
  node_game_updater["Game Updater<br/>[game_updater.py]"]
  node_instagram["Instagram Tools<br/>[instagram_mcp.py]"]
  node_circuit["Circuit Assembler"]
  node_skills["Skill Crucible<br/>[skill_forge.py]"]
  node_autoheal["Auto-Heal Engine"]
  node_smart_home["Smart Home Service<br/>[service.py]"]
end

subgraph group_connect["Android Connect"]
  node_gateway["Connect Gateway<br/>[server.py]"]
  node_device_manager[("Device Registry<br/>[device_manager.py]")]
  node_protocol["Connect Protocol<br/>[protocol.py]"]
  node_gateway_ws["Gateway WebSocket<br/>[websocket.py]"]
  node_android_service["Android Service"]
  node_device_commands["Device Commands"]
  node_agent_state[("Agent State Store<br/>[AgentStateStore.kt]")]
end

subgraph group_services["Supporting Services"]
  node_smart_storage[("Smart Home Storage<br/>[storage.py]")]
  node_undo["Undo Support<br/>[undo.py]"]
  node_user_paths["User Data Paths<br/>[user_paths.py]"]
  node_openrouter["OpenRouter Client<br/>[or_client.py]"]
end

node_user(("User"))

node_user -->|"issues requests"| node_ui
node_ui -->|"submits input"| node_main
node_main -.->|"plans tasks"| node_planner
node_main -.->|"dispatches actions"| node_executor
node_main -->|"updates interface"| node_ui
node_planner -.->|"reasons with"| node_llm
node_executor -.->|"queues tasks"| node_task_queue
node_executor -.->|"runs tools"| node_file_processor
node_executor -.->|"runs tools"| node_computer_settings
node_executor -.->|"runs tools"| node_game_updater
node_executor -.->|"runs tools"| node_instagram
node_executor -.->|"runs tools"| node_circuit
node_llm -->|"uses provider"| node_openrouter
node_llm -.->|"uses memory"| node_memory
node_main -->|"uses reasoning"| node_local_brain
node_skills -.->|"synthesizes skills"| node_llm
node_main -->|"supports skill creation"| node_skills
node_autoheal -->|"analyzes failures"| node_llm
node_main -->|"supports repair"| node_autoheal
node_smart_home -->|"stores device data"| node_smart_storage
node_user -->|"uses dashboard"| node_dashboard
node_android_service -->|"creates handler"| node_device_commands
node_android_service -->|"connects websocket"| node_gateway_ws
node_android_service -.->|"tracks connection"| node_agent_state
node_gateway -->|"manages devices"| node_device_manager
node_gateway -->|"builds messages"| node_protocol
node_gateway -->|"uses transport"| node_gateway_ws
node_file_processor -.->|"registers undo"| node_undo
node_computer_settings -->|"registers undo"| node_undo
node_llm -->|"loads data paths"| node_user_paths
node_memory -->|"loads data paths"| node_user_paths

click node_main "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/main.py"
click node_ui "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/ui.py"
click node_dashboard "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/dashboard/server.py"
click node_planner "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/planner.py"
click node_executor "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/executor.py"
click node_task_queue "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/task_queue.py"
click node_llm "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/llm_client.py"
click node_memory "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/memory/memory_manager.py"
click node_local_brain "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/local_brain.py"
click node_file_processor "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/file_processor.py"
click node_computer_settings "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/computer_settings.py"
click node_game_updater "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/game_updater.py"
click node_instagram "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/instagram_mcp.py"
click node_circuit "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/circuit_assembler.py"
click node_skills "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/skill_forge.py"
click node_autoheal "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/auto_heal_engine.py"
click node_smart_home "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/smart_home/service.py"
click node_smart_storage "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/smart_home/storage.py"
click node_gateway "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/server.py"
click node_device_manager "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/device_manager.py"
click node_protocol "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/protocol.py"
click node_gateway_ws "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/websocket.py"
click node_android_service "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt"
click node_device_commands "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/commands/DeviceCommandHandler.kt"
click node_agent_state "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/core/AgentStateStore.kt"
click node_undo "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/undo.py"
click node_user_paths "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/user_paths.py"
click node_openrouter "https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/or_client.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_ui,node_dashboard,node_user toneBlue
class node_planner,node_executor,node_task_queue,node_llm,node_memory,node_local_brain toneAmber
class node_file_processor,node_computer_settings,node_game_updater,node_instagram,node_circuit,node_skills,node_autoheal,node_smart_home toneMint
class node_gateway,node_device_manager,node_protocol,node_gateway_ws,node_android_service,node_device_commands,node_agent_state toneRose
class node_smart_storage,node_undo,node_user_paths,node_openrouter toneIndigo
```

## Components

### Desktop Experience

- [Application Loop](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/main.py): `main.py`
- [Command UI](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/ui.py): `ui.py`
- [Local Dashboard](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/dashboard/server.py): `dashboard/server.py`

### Agent and Memory

- [Task Planner](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/planner.py): `agent/planner.py`
- [Action Executor](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/executor.py): `agent/executor.py`
- [Task Queue](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/agent/task_queue.py): `agent/task_queue.py`
- [Unified AI Client](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/llm_client.py): `llm_client.py`
- [Long-Term Memory](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/memory/memory_manager.py): `memory/memory_manager.py`
- [Local Brain](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/local_brain.py): `core/local_brain.py`

### Desktop Capabilities

- [File Processing](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/file_processor.py): `actions/file_processor.py`
- [System Settings](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/computer_settings.py): `actions/computer_settings.py`
- [Game Updater](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/game_updater.py): `actions/game_updater.py`
- [Instagram Tools](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/instagram_mcp.py): `actions/instagram_mcp.py`
- [Circuit Assembler](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/circuit_assembler.py): `actions/circuit_assembler.py`
- [Skill Crucible](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/skill_forge.py): `core/skill_forge.py`
- [Auto-Heal Engine](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/actions/auto_heal_engine.py): `actions/auto_heal_engine.py`
- [Smart Home Service](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/smart_home/service.py): `smart_home/service.py`

### Android Connect

- [Connect Gateway](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/server.py): `brahma_connect/gateway/server.py`
- [Device Registry](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/device_manager.py): `brahma_connect/gateway/device_manager.py`
- [Connect Protocol](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/protocol.py): `brahma_connect/gateway/protocol.py`
- [Gateway WebSocket](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma_connect/gateway/websocket.py): `brahma_connect/gateway/websocket.py`
- [Android Service](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt): `brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt`
- [Device Commands](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/commands/DeviceCommandHandler.kt): `brahma-connect-android/app/src/main/java/com/brahma/connect/commands/DeviceCommandHandler.kt`
- [Agent State Store](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/brahma-connect-android/app/src/main/java/com/brahma/connect/core/AgentStateStore.kt): `brahma-connect-android/app/src/main/java/com/brahma/connect/core/AgentStateStore.kt`

### Supporting Services

- [Smart Home Storage](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/smart_home/storage.py): `smart_home/storage.py`
- [Undo Support](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/undo.py): `core/undo.py`
- [User Data Paths](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/core/user_paths.py): `core/user_paths.py`
- [OpenRouter Client](https://github.com/titechprabhasolutions/brahma-ai-evo/blob/main/or_client.py): `or_client.py`

### Other components

- **User**

## Connections

- User → Command UI: issues requests (evidence: `README.md`)
- Command UI → Application Loop: submits input (evidence: `README.md`)
- Application Loop → Task Planner: plans tasks
- Application Loop → Action Executor: dispatches actions
- Application Loop → Command UI: updates interface (evidence: `README.md`)
- Task Planner → Unified AI Client: reasons with
- Action Executor → Task Queue: queues tasks
- Action Executor → File Processing: runs tools
- Action Executor → System Settings: runs tools
- Action Executor → Game Updater: runs tools
- Action Executor → Instagram Tools: runs tools
- Action Executor → Circuit Assembler: runs tools
- Unified AI Client → OpenRouter Client: uses provider (evidence: `llm_client.py`)
- Unified AI Client → Long-Term Memory: uses memory
- Application Loop → Local Brain: uses reasoning (evidence: `main.py`)
- Skill Crucible → Unified AI Client: synthesizes skills
- Application Loop → Skill Crucible: supports skill creation (evidence: `README.md`)
- Auto-Heal Engine → Unified AI Client: analyzes failures (evidence: `actions/auto_heal_engine.py`)
- Application Loop → Auto-Heal Engine: supports repair (evidence: `README.md`)
- Smart Home Service → Smart Home Storage: stores device data (evidence: `smart_home/service.py`)
- User → Local Dashboard: uses dashboard (evidence: `README.md`)
- Android Service → Device Commands: creates handler (evidence: `brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt`)
- Android Service → Gateway WebSocket: connects websocket (evidence: `brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt`)
- Android Service → Agent State Store: tracks connection (evidence: `brahma-connect-android/app/src/main/java/com/brahma/connect/BrahmaConnectForegroundService.kt`)
- Connect Gateway → Device Registry: manages devices (evidence: `brahma_connect/gateway/server.py`)
- Connect Gateway → Connect Protocol: builds messages (evidence: `brahma_connect/gateway/server.py`)
- Connect Gateway → Gateway WebSocket: uses transport (evidence: `brahma_connect/gateway/server.py`)
- File Processing → Undo Support: registers undo
- System Settings → Undo Support: registers undo (evidence: `actions/computer_settings.py`)
- Unified AI Client → User Data Paths: loads data paths (evidence: `llm_client.py`)
- Long-Term Memory → User Data Paths: loads data paths (evidence: `memory/memory_manager.py`)
