# nurasss/ai-office architecture

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

- Interactive diagram: https://gitdiagram.com/nurasss/ai-office
- Repository: https://github.com/nurasss/ai-office

## Overview

AI Office is a personal multi-agent office with web/API and Telegram entry points, a task and project runtime, and an autonomous planning/approval loop. A typical request enters through the product API, is routed to an agent, and returns a result; autonomous work additionally plans and runs tasks, with guarded actions requiring approval. The graph preserves documented RAG, memory, integrations, and scheduling capabilities. Some subsystem paths and links are based on README or source-index references rather than inspected implementation excerpts.

Main entry points: [`services/autonomy_service.py`](https://github.com/nurasss/ai-office/blob/main/services/autonomy_service.py) (Autonomy loop), [`api/autonomous.py`](https://github.com/nurasss/ai-office/blob/main/api/autonomous.py) (Autonomy API), [`services/task_service.py`](https://github.com/nurasss/ai-office/blob/main/services/task_service.py) (Task engine), [`agents/base/base_agent.py`](https://github.com/nurasss/ai-office/blob/main/agents/base/base_agent.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product interfaces"]
  node_product_api["Product API<br/>[office.py]"]
  node_autonomy_api["Autonomy API<br/>[autonomous.py]"]
  node_web["Web and bot app<br/>[app.py]"]
end

subgraph group_work["Agent work"]
  node_orchestrator["Agent routing<br/>[orchestrator.py]"]
  node_agents["Specialist agents"]
  node_base_agent["Agent runtime<br/>[base_agent.py]"]
  node_llm["LLM routing<br/>[llm_router.py]"]
end

subgraph group_runtime["Autonomous runtime"]
  node_tasks["Task engine<br/>[task_service.py]"]
  node_projects["Project service<br/>[project_service.py]"]
  node_autonomy["Autonomy loop"]
  node_planner["PMO planner<br/>[pmo_planner.py]"]
  node_approvals["Approval service"]
  node_policy["Action policy<br/>[action_policy.py]"]
  node_scheduler["Scheduler<br/>[scheduler.py]"]
  node_database[("SQL database<br/>[db.py]")]
  node_models["Runtime records<br/>[models.py]"]
end

subgraph group_knowledge["Knowledge and integrations"]
  node_retriever["RAG retriever<br/>[retriever.py]"]
  node_vector[("Vector store<br/>[vector_store.py]")]
  node_memory[("Long-term memory")]
  node_tools["External tools"]
  node_web_tools["Public web tools<br/>[web_tools.py]"]
end

node_user(("User"))
node_telegram(("Telegram"))

node_user -->|"submits task"| node_product_api
node_user -->|"manages runtime"| node_autonomy_api
node_telegram -->|"sends commands"| node_web
node_product_api -->|"routes requests"| node_agents
node_product_api -->|"queries context"| node_retriever
node_web -->|"routes runtime API"| node_autonomy_api
node_web -->|"dispatches tasks"| node_agents
node_orchestrator -->|"routes work"| node_agents
node_agents -->|"inherit runtime"| node_base_agent
node_base_agent -->|"selects models"| node_llm
node_base_agent -->|"retrieves knowledge"| node_retriever
node_base_agent -->|"records outcomes"| node_memory
node_base_agent -->|"adds read tools"| node_web_tools
node_agents -->|"uses integrations"| node_tools
node_retriever -->|"searches and writes"| node_vector
node_autonomy_api -->|"invokes runtime"| node_autonomy
node_autonomy_api -->|"serves task operations"| node_tasks
node_autonomy_api -->|"serves projects"| node_projects
node_autonomy_api -->|"serves decisions"| node_approvals
node_autonomy -->|"requests plans"| node_planner
node_autonomy -->|"creates and runs"| node_tasks
node_autonomy -->|"checks approvals"| node_approvals
node_autonomy -->|"loads projects"| node_projects
node_autonomy -.->|"scheduled by"| node_scheduler
node_approvals -->|"records events"| node_tasks
node_tasks -->|"resolves project"| node_projects
node_tasks -->|"checks actions"| node_policy
node_tasks -.->|"persists tasks"| node_database
node_approvals -.->|"persists decisions"| node_database
node_database -.->|"stores records"| node_models
node_autonomy -->|"notifies user"| node_telegram

click node_product_api "https://github.com/nurasss/ai-office/blob/main/api/office.py"
click node_autonomy_api "https://github.com/nurasss/ai-office/blob/main/api/autonomous.py"
click node_web "https://github.com/nurasss/ai-office/blob/main/web/app.py"
click node_orchestrator "https://github.com/nurasss/ai-office/blob/main/orchestrator.py"
click node_agents "https://github.com/nurasss/ai-office/tree/main/agents"
click node_base_agent "https://github.com/nurasss/ai-office/blob/main/agents/base/base_agent.py"
click node_llm "https://github.com/nurasss/ai-office/blob/main/core/llm_router.py"
click node_tasks "https://github.com/nurasss/ai-office/blob/main/services/task_service.py"
click node_projects "https://github.com/nurasss/ai-office/blob/main/services/project_service.py"
click node_autonomy "https://github.com/nurasss/ai-office/blob/main/services/autonomy_service.py"
click node_planner "https://github.com/nurasss/ai-office/blob/main/services/pmo_planner.py"
click node_approvals "https://github.com/nurasss/ai-office/blob/main/services/approval_service.py"
click node_policy "https://github.com/nurasss/ai-office/blob/main/core/action_policy.py"
click node_scheduler "https://github.com/nurasss/ai-office/blob/main/services/scheduler.py"
click node_database "https://github.com/nurasss/ai-office/blob/main/core/db.py"
click node_models "https://github.com/nurasss/ai-office/blob/main/core/models.py"
click node_retriever "https://github.com/nurasss/ai-office/blob/main/rag/retriever.py"
click node_vector "https://github.com/nurasss/ai-office/blob/main/rag/vector_store.py"
click node_memory "https://github.com/nurasss/ai-office/blob/main/memory/long_term_memory.py"
click node_tools "https://github.com/nurasss/ai-office/tree/main/tools/external"
click node_web_tools "https://github.com/nurasss/ai-office/blob/main/tools/external/web_tools.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_product_api,node_autonomy_api,node_web,node_user toneBlue
class node_orchestrator,node_agents,node_base_agent,node_llm toneAmber
class node_tasks,node_projects,node_autonomy,node_planner,node_approvals,node_policy,node_scheduler,node_database,node_models toneMint
class node_retriever,node_vector,node_memory,node_tools,node_web_tools toneRose
class node_telegram toneIndigo
```

## Components

### Product interfaces

- [Product API](https://github.com/nurasss/ai-office/blob/main/api/office.py): `api/office.py`
- [Autonomy API](https://github.com/nurasss/ai-office/blob/main/api/autonomous.py): `api/autonomous.py`
- [Web and bot app](https://github.com/nurasss/ai-office/blob/main/web/app.py): `web/app.py`

### Agent work

- [Agent routing](https://github.com/nurasss/ai-office/blob/main/orchestrator.py): `orchestrator.py`
- [Specialist agents](https://github.com/nurasss/ai-office/tree/main/agents): `agents`
- [Agent runtime](https://github.com/nurasss/ai-office/blob/main/agents/base/base_agent.py): `agents/base/base_agent.py`
- [LLM routing](https://github.com/nurasss/ai-office/blob/main/core/llm_router.py): `core/llm_router.py`

### Autonomous runtime

- [Task engine](https://github.com/nurasss/ai-office/blob/main/services/task_service.py): `services/task_service.py`
- [Project service](https://github.com/nurasss/ai-office/blob/main/services/project_service.py): `services/project_service.py`
- [Autonomy loop](https://github.com/nurasss/ai-office/blob/main/services/autonomy_service.py): `services/autonomy_service.py`
- [PMO planner](https://github.com/nurasss/ai-office/blob/main/services/pmo_planner.py): `services/pmo_planner.py`
- [Approval service](https://github.com/nurasss/ai-office/blob/main/services/approval_service.py): `services/approval_service.py`
- [Action policy](https://github.com/nurasss/ai-office/blob/main/core/action_policy.py): `core/action_policy.py`
- [Scheduler](https://github.com/nurasss/ai-office/blob/main/services/scheduler.py): `services/scheduler.py`
- [SQL database](https://github.com/nurasss/ai-office/blob/main/core/db.py): `core/db.py`
- [Runtime records](https://github.com/nurasss/ai-office/blob/main/core/models.py): `core/models.py`

### Knowledge and integrations

- [RAG retriever](https://github.com/nurasss/ai-office/blob/main/rag/retriever.py): `rag/retriever.py`
- [Vector store](https://github.com/nurasss/ai-office/blob/main/rag/vector_store.py): `rag/vector_store.py`
- [Long-term memory](https://github.com/nurasss/ai-office/blob/main/memory/long_term_memory.py): `memory/long_term_memory.py`
- [External tools](https://github.com/nurasss/ai-office/tree/main/tools/external): `tools/external`
- [Public web tools](https://github.com/nurasss/ai-office/blob/main/tools/external/web_tools.py): `tools/external/web_tools.py`

### Other components

- **User**
- **Telegram**

## Connections

- User → Product API: submits task
- User → Autonomy API: manages runtime
- Telegram → Web and bot app: sends commands
- Product API → Specialist agents: routes requests (evidence: `api/office.py`)
- Product API → RAG retriever: queries context (evidence: `api/office.py`)
- Web and bot app → Autonomy API: routes runtime API (evidence: `web/app.py`)
- Web and bot app → Specialist agents: dispatches tasks (evidence: `web/app.py`)
- Agent routing → Specialist agents: routes work (evidence: `orchestrator.py`)
- Specialist agents → Agent runtime: inherit runtime (evidence: `agents/__init__.py`)
- Agent runtime → LLM routing: selects models (evidence: `agents/base/base_agent.py`)
- Agent runtime → RAG retriever: retrieves knowledge (evidence: `agents/base/base_agent.py`)
- Agent runtime → Long-term memory: records outcomes (evidence: `agents/base/base_agent.py`)
- Agent runtime → Public web tools: adds read tools (evidence: `agents/base/base_agent.py`)
- Specialist agents → External tools: uses integrations (evidence: `agents/pmo/pmo_agent.py`)
- RAG retriever → Vector store: searches and writes (evidence: `rag/retriever.py`)
- Autonomy API → Autonomy loop: invokes runtime (evidence: `api/autonomous.py`)
- Autonomy API → Task engine: serves task operations (evidence: `api/autonomous.py`)
- Autonomy API → Project service: serves projects (evidence: `api/autonomous.py`)
- Autonomy API → Approval service: serves decisions (evidence: `api/autonomous.py`)
- Autonomy loop → PMO planner: requests plans (evidence: `services/autonomy_service.py`)
- Autonomy loop → Task engine: creates and runs (evidence: `services/autonomy_service.py`)
- Autonomy loop → Approval service: checks approvals (evidence: `services/autonomy_service.py`)
- Autonomy loop → Project service: loads projects (evidence: `services/autonomy_service.py`)
- Autonomy loop → Scheduler: scheduled by
- Approval service → Task engine: records events (evidence: `services/approval_service.py`)
- Task engine → Project service: resolves project (evidence: `services/task_service.py`)
- Task engine → Action policy: checks actions (evidence: `services/task_service.py`)
- Task engine → SQL database: persists tasks
- Approval service → SQL database: persists decisions
- SQL database → Runtime records: stores records
- Autonomy loop → Telegram: notifies user (evidence: `services/autonomy_service.py`)