# tamimlabs/nexusmind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/tamimlabs/nexusmind-ai
- Repository: https://github.com/tamimlabs/nexusmind-ai

## Overview

NexusMind is an autonomous, event-driven task-execution agent: users submit goals, or watchers detect platform events; the system checks standing instructions, plans and executes work, then returns results and learns from the task. The README documents adaptive execution, memory-gated watchers, platform write-back skills, approvals, live task updates, and self-evolving skills. The sampled source confirms the API, orchestrator, memory retrieval, watcher lifecycle, Gemini client, and Firestore roles; some subsystem links reflect README documentation rather than inspected implementation.

Main entry points: [`agent/orchestrator.py`](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/orchestrator.py) (Task Orchestrator), [`agent/watchers`](https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/watchers) (Event Watchers), [`api/main.py`](https://github.com/tamimlabs/nexusmind-ai/blob/master/api/main.py) (Task API), [`agent/core/agent_loop.py`](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/agent_loop.py) (Adaptive Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Events"]
  node_api["Task API<br/>[main.py]"]
  node_watcher_api["Watcher API<br/>[watcher_routes.py]"]
  node_watcher_manager["Watcher Manager<br/>[manager.py]"]
  node_watchers["Event Watchers"]
end

subgraph group_runtime["Task Runtime"]
  node_orchestrator["Task Orchestrator<br/>[orchestrator.py]"]
  node_planner["Task Planner<br/>[planner.py]"]
  node_agent_loop["Adaptive Loop<br/>[agent_loop.py]"]
  node_executor["Tool Executor<br/>[executor.py]"]
  node_gemini["Gemini Client<br/>[gemini_client.py]"]
end

subgraph group_integrations["Skills and Safety"]
  node_skill_library["Skill Library<br/>[skill_library.py]"]
  node_platform_skills["Platform Skills"]
  node_approval["Approval and Steering<br/>[telegram.py]"]
end

subgraph group_learning["Memory and Learning"]
  node_memory[("Hybrid Memory")]
  node_retrieval["Memory Retrieval<br/>[retrieval.py]"]
end

subgraph group_platform["Cloud Platform"]
  node_firestore[("Firestore<br/>[client.py]")]
  node_pubsub["Pub/Sub Events<br/>[events.py]"]
  node_adk["ADK Agent<br/>[agent.py]"]
end

node_user(("User"))
node_external_events(("Platform Events"))
node_telegram_service(("Telegram"))
node_connected_platforms(("Connected Services"))

node_user -->|"submits goal"| node_api
node_api -->|"dispatches task"| node_orchestrator
node_api -->|"manages watchers"| node_watcher_api
node_watcher_api -->|"controls lifecycle"| node_watcher_manager
node_watcher_manager -->|"creates and starts"| node_watchers
node_connected_platforms -->|"provide events"| node_watchers
node_external_events -.->|"deliver webhook"| node_watchers
node_watchers -->|"trigger task"| node_orchestrator
node_orchestrator -->|"recalls context"| node_retrieval
node_retrieval -->|"searches facts"| node_memory
node_orchestrator -->|"plans task"| node_planner
node_orchestrator -->|"runs task"| node_agent_loop
node_agent_loop -->|"requests decisions"| node_gemini
node_agent_loop -->|"executes actions"| node_executor
node_executor -->|"invokes tools"| node_platform_skills
node_platform_skills -->|"reads and writes"| node_connected_platforms
node_executor -->|"requests approval"| node_approval
node_approval -->|"sends approval"| node_telegram_service
node_orchestrator -->|"stores reflections"| node_memory
node_orchestrator -->|"synthesizes skills"| node_skill_library
node_skill_library -->|"makes skills available"| node_platform_skills
node_orchestrator -.->|"persists task state"| node_firestore
node_orchestrator -.->|"publishes events"| node_pubsub
node_pubsub -.->|"triggers agent"| node_adk
node_adk -.->|"falls back to"| node_orchestrator

click node_api "https://github.com/tamimlabs/nexusmind-ai/blob/master/api/main.py"
click node_watcher_api "https://github.com/tamimlabs/nexusmind-ai/blob/master/api/watcher_routes.py"
click node_watcher_manager "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/watchers/manager.py"
click node_watchers "https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/watchers"
click node_orchestrator "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/orchestrator.py"
click node_planner "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/planner.py"
click node_agent_loop "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/agent_loop.py"
click node_executor "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/executor.py"
click node_gemini "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/gemini_client.py"
click node_skill_library "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/skill_library.py"
click node_platform_skills "https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/skills"
click node_approval "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/telegram.py"
click node_memory "https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/core/memory"
click node_retrieval "https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/memory/retrieval.py"
click node_firestore "https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/firestore/client.py"
click node_pubsub "https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/pubsub/events.py"
click node_adk "https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/vertex_ai/agent.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_api,node_watcher_api,node_watcher_manager,node_watchers,node_user toneBlue
class node_orchestrator,node_planner,node_agent_loop,node_executor,node_gemini toneAmber
class node_skill_library,node_platform_skills,node_approval toneMint
class node_memory,node_retrieval toneRose
class node_firestore,node_pubsub,node_adk,node_external_events,node_telegram_service,node_connected_platforms toneIndigo
```

## Components

### Entry and Events

- [Task API](https://github.com/tamimlabs/nexusmind-ai/blob/master/api/main.py): `api/main.py`
- [Watcher API](https://github.com/tamimlabs/nexusmind-ai/blob/master/api/watcher_routes.py): `api/watcher_routes.py`
- [Watcher Manager](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/watchers/manager.py): `agent/watchers/manager.py`
- [Event Watchers](https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/watchers): `agent/watchers`

### Task Runtime

- [Task Orchestrator](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/orchestrator.py): `agent/orchestrator.py`
- [Task Planner](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/planner.py): `agent/core/planner.py`
- [Adaptive Loop](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/agent_loop.py): `agent/core/agent_loop.py`
- [Tool Executor](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/executor.py): `agent/core/executor.py`
- [Gemini Client](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/gemini_client.py): `agent/core/gemini_client.py`

### Skills and Safety

- [Skill Library](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/skill_library.py): `agent/core/skill_library.py`
- [Platform Skills](https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/skills): `agent/skills`
- [Approval and Steering](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/telegram.py): `agent/telegram.py`

### Memory and Learning

- [Hybrid Memory](https://github.com/tamimlabs/nexusmind-ai/tree/master/agent/core/memory): `agent/core/memory`
- [Memory Retrieval](https://github.com/tamimlabs/nexusmind-ai/blob/master/agent/core/memory/retrieval.py): `agent/core/memory/retrieval.py`

### Cloud Platform

- [Firestore](https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/firestore/client.py): `cloud/firestore/client.py`
- [Pub/Sub Events](https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/pubsub/events.py): `cloud/pubsub/events.py`
- [ADK Agent](https://github.com/tamimlabs/nexusmind-ai/blob/master/cloud/vertex_ai/agent.py): `cloud/vertex_ai/agent.py`

### Other components

- **User**
- **Platform Events**
- **Telegram**
- **Connected Services**

## Connections

- User → Task API: submits goal
- Task API → Task Orchestrator: dispatches task
- Task API → Watcher API: manages watchers
- Watcher API → Watcher Manager: controls lifecycle
- Watcher Manager → Event Watchers: creates and starts
- Connected Services → Event Watchers: provide events
- Platform Events → Event Watchers: deliver webhook
- Event Watchers → Task Orchestrator: trigger task
- Task Orchestrator → Memory Retrieval: recalls context
- Memory Retrieval → Hybrid Memory: searches facts
- Task Orchestrator → Task Planner: plans task
- Task Orchestrator → Adaptive Loop: runs task
- Adaptive Loop → Gemini Client: requests decisions
- Adaptive Loop → Tool Executor: executes actions
- Tool Executor → Platform Skills: invokes tools
- Platform Skills → Connected Services: reads and writes
- Tool Executor → Approval and Steering: requests approval
- Approval and Steering → Telegram: sends approval
- Task Orchestrator → Hybrid Memory: stores reflections
- Task Orchestrator → Skill Library: synthesizes skills
- Skill Library → Platform Skills: makes skills available
- Task Orchestrator → Firestore: persists task state
- Task Orchestrator → Pub/Sub Events: publishes events
- Pub/Sub Events → ADK Agent: triggers agent
- ADK Agent → Task Orchestrator: falls back to