# getnao/nao architecture

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

- Interactive diagram: https://gitdiagram.com/getnao/nao
- Repository: https://github.com/getnao/nao

## Overview

nao is an agentic BI product: teams build and evaluate governed context, then users ask data questions and turn results into shareable stories through the web app or integrations. The backend routes requests to agent, query, and story services, with project and chat state persisted in its database. The CLI supports context setup and synchronization; README also documents offline evaluation, deployment, usage observation, and recommendation workflows. Relationships below use only shown calls and README-described capabilities; several product branches have directory-level paths because their implementation was not sampled.

Main entry points: [`apps/backend/src/services/agent.ts`](https://github.com/getnao/nao/blob/main/apps/backend/src/services/agent.ts) (Agent runtime), [`apps/backend/src/services/local-query.service.ts`](https://github.com/getnao/nao/blob/main/apps/backend/src/services/local-query.service.ts) (Query tools), [`apps/frontend/src/main.tsx`](https://github.com/getnao/nao/blob/main/apps/frontend/src/main.tsx) (Web app), [`apps/backend/src/queries/chat.queries.ts`](https://github.com/getnao/nao/blob/main/apps/backend/src/queries/chat.queries.ts) (Chat history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_context["Context tooling"]
  node_cli["nao CLI<br/>[main.py]"]
  node_sync["Context sync"]
  node_templates["Context templates<br/>[engine.py]"]
  node_eval["Offline evaluation"]
  node_live_context["Live context review"]
end

subgraph group_conversation["Analysis experience"]
  node_web["Web app<br/>[main.tsx]"]
  node_agent_routes["Agent API<br/>[agent.ts]"]
  node_agent["Agent runtime<br/>[agent.ts]"]
  node_semantic_editor["Semantic query editor"]
  node_query_tools["Query tools"]
  node_query_results["Query result paging"]
  node_stories["Stories and dashboards<br/>[custom-story.ts]"]
end

subgraph group_platform["Backend platform"]
  node_chat_state["Chat history<br/>[chat.queries.ts]"]
  node_projects["Project access<br/>[project.queries.ts]"]
  node_db[("Application database<br/>[db.ts]")]
  node_storage[("File storage<br/>[index.ts]")]
  node_server["API server<br/>[app.ts]"]
end

subgraph group_integrations["External channels"]
  node_mcp["MCP endpoint<br/>[routes.ts]"]
  node_channels["Messaging channels"]
end

node_data_team(("Data team"))
node_analyst(("Company analyst"))
node_context_repo["Context repository"]
node_warehouse[("Analytics warehouse")]
node_mcp_client(("MCP client"))
node_messaging_user(("Messaging user"))
node_llm{{"LLM provider"}}

node_data_team -->|"sets up"| node_cli
node_cli -->|"runs sync"| node_sync
node_sync -->|"writes context"| node_context_repo
node_data_team -->|"evaluates changes"| node_eval
node_data_team -.->|"reviews updates"| node_live_context
node_analyst -->|"asks questions"| node_web
node_web -->|"sends requests"| node_server
node_server -->|"registers routes"| node_agent_routes
node_agent_routes -.->|"runs agent"| node_agent
node_agent -.->|"requests generation"| node_llm
node_agent -.->|"invokes queries"| node_query_tools
node_query_tools -.->|"queries data"| node_warehouse
node_query_tools -->|"opens files"| node_storage
node_semantic_editor -->|"supports authoring"| node_web
node_query_results -->|"loads saved output"| node_chat_state
node_query_results -->|"checks active run"| node_agent
node_agent -.->|"persists conversation"| node_chat_state
node_projects -.->|"reads and writes"| node_db
node_chat_state -.->|"stores history"| node_db
node_stories -.->|"shares stories"| node_analyst
node_mcp_client -->|"calls tools"| node_mcp
node_mcp -.->|"creates server"| node_agent
node_messaging_user -->|"asks questions"| node_channels
node_channels -.->|"routes requests"| node_agent
node_templates -->|"generates text"| node_llm
node_live_context -->|"reads updates"| node_context_repo

click node_cli "https://github.com/getnao/nao/blob/main/cli/nao_core/main.py"
click node_sync "https://github.com/getnao/nao/tree/main/cli/nao_core/commands/sync"
click node_templates "https://github.com/getnao/nao/blob/main/cli/nao_core/templates/engine.py"
click node_eval "https://github.com/getnao/nao/tree/main/cli/nao_core/commands/test"
click node_live_context "https://github.com/getnao/nao/blob/main/apps/backend/src/services/context-explorer-git/live-context.service.ts"
click node_web "https://github.com/getnao/nao/blob/main/apps/frontend/src/main.tsx"
click node_agent_routes "https://github.com/getnao/nao/blob/main/apps/backend/src/routes/agent.ts"
click node_agent "https://github.com/getnao/nao/blob/main/apps/backend/src/services/agent.ts"
click node_semantic_editor "https://github.com/getnao/nao/blob/main/apps/frontend/src/components/side-panel/semantic-query-editor.tsx"
click node_query_tools "https://github.com/getnao/nao/blob/main/apps/backend/src/services/local-query.service.ts"
click node_query_results "https://github.com/getnao/nao/blob/main/apps/backend/src/services/query-rows.service.ts"
click node_stories "https://github.com/getnao/nao/blob/main/apps/backend/src/services/custom-story.ts"
click node_chat_state "https://github.com/getnao/nao/blob/main/apps/backend/src/queries/chat.queries.ts"
click node_projects "https://github.com/getnao/nao/blob/main/apps/backend/src/queries/project.queries.ts"
click node_db "https://github.com/getnao/nao/blob/main/apps/backend/src/db/db.ts"
click node_storage "https://github.com/getnao/nao/blob/main/apps/backend/src/services/storage/index.ts"
click node_server "https://github.com/getnao/nao/blob/main/apps/backend/src/app.ts"
click node_mcp "https://github.com/getnao/nao/blob/main/apps/backend/src/mcp/routes.ts"
click node_channels "https://github.com/getnao/nao/tree/main/apps/backend/src/routes"

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_sync,node_templates,node_eval,node_live_context,node_mcp_client,node_messaging_user toneBlue
class node_web,node_agent_routes,node_agent,node_semantic_editor,node_query_tools,node_query_results,node_stories,node_warehouse toneAmber
class node_chat_state,node_projects,node_db,node_storage,node_server toneMint
class node_mcp,node_channels toneRose
class node_data_team,node_analyst,node_context_repo,node_llm toneIndigo
```

## Components

### Context tooling

- [nao CLI](https://github.com/getnao/nao/blob/main/cli/nao_core/main.py): `cli/nao_core/main.py`
- [Context sync](https://github.com/getnao/nao/tree/main/cli/nao_core/commands/sync): `cli/nao_core/commands/sync`
- [Context templates](https://github.com/getnao/nao/blob/main/cli/nao_core/templates/engine.py): `cli/nao_core/templates/engine.py`
- [Offline evaluation](https://github.com/getnao/nao/tree/main/cli/nao_core/commands/test): `cli/nao_core/commands/test`
- [Live context review](https://github.com/getnao/nao/blob/main/apps/backend/src/services/context-explorer-git/live-context.service.ts): `apps/backend/src/services/context-explorer-git/live-context.service.ts`

### Analysis experience

- [Web app](https://github.com/getnao/nao/blob/main/apps/frontend/src/main.tsx): `apps/frontend/src/main.tsx`
- [Agent API](https://github.com/getnao/nao/blob/main/apps/backend/src/routes/agent.ts): `apps/backend/src/routes/agent.ts`
- [Agent runtime](https://github.com/getnao/nao/blob/main/apps/backend/src/services/agent.ts): `apps/backend/src/services/agent.ts`
- [Semantic query editor](https://github.com/getnao/nao/blob/main/apps/frontend/src/components/side-panel/semantic-query-editor.tsx): `apps/frontend/src/components/side-panel/semantic-query-editor.tsx`
- [Query tools](https://github.com/getnao/nao/blob/main/apps/backend/src/services/local-query.service.ts): `apps/backend/src/services/local-query.service.ts`
- [Query result paging](https://github.com/getnao/nao/blob/main/apps/backend/src/services/query-rows.service.ts): `apps/backend/src/services/query-rows.service.ts`
- [Stories and dashboards](https://github.com/getnao/nao/blob/main/apps/backend/src/services/custom-story.ts): `apps/backend/src/services/custom-story.ts`

### Backend platform

- [Chat history](https://github.com/getnao/nao/blob/main/apps/backend/src/queries/chat.queries.ts): `apps/backend/src/queries/chat.queries.ts`
- [Project access](https://github.com/getnao/nao/blob/main/apps/backend/src/queries/project.queries.ts): `apps/backend/src/queries/project.queries.ts`
- [Application database](https://github.com/getnao/nao/blob/main/apps/backend/src/db/db.ts): `apps/backend/src/db/db.ts`
- [File storage](https://github.com/getnao/nao/blob/main/apps/backend/src/services/storage/index.ts): `apps/backend/src/services/storage/index.ts`
- [API server](https://github.com/getnao/nao/blob/main/apps/backend/src/app.ts): `apps/backend/src/app.ts`

### External channels

- [MCP endpoint](https://github.com/getnao/nao/blob/main/apps/backend/src/mcp/routes.ts): `apps/backend/src/mcp/routes.ts`
- [Messaging channels](https://github.com/getnao/nao/tree/main/apps/backend/src/routes): `apps/backend/src/routes`

### Other components

- **Data team**
- **Company analyst**
- **Context repository**
- **Analytics warehouse**
- **MCP client**
- **Messaging user**
- **LLM provider**

## Connections

- Data team → nao CLI: sets up (evidence: `README.md`)
- nao CLI → Context sync: runs sync (evidence: `cli/nao_core/main.py`)
- Context sync → Context repository: writes context (evidence: `README.md`)
- Data team → Offline evaluation: evaluates changes (evidence: `README.md`)
- Data team → Live context review: reviews updates
- Company analyst → Web app: asks questions (evidence: `README.md`)
- Web app → API server: sends requests (evidence: `apps/frontend/src/main.tsx`)
- API server → Agent API: registers routes (evidence: `apps/backend/src/app.ts`)
- Agent API → Agent runtime: runs agent
- Agent runtime → LLM provider: requests generation
- Agent runtime → Query tools: invokes queries
- Query tools → Analytics warehouse: queries data
- Query tools → File storage: opens files (evidence: `apps/backend/src/services/local-query.service.ts`)
- Semantic query editor → Web app: supports authoring (evidence: `apps/frontend/src/components/side-panel/semantic-query-editor.tsx`)
- Query result paging → Chat history: loads saved output (evidence: `apps/backend/src/services/query-rows.service.ts`)
- Query result paging → Agent runtime: checks active run (evidence: `apps/backend/src/services/query-rows.service.ts`)
- Agent runtime → Chat history: persists conversation
- Project access → Application database: reads and writes (evidence: `apps/backend/src/queries/project.queries.ts`)
- Chat history → Application database: stores history
- Stories and dashboards → Company analyst: shares stories
- MCP client → MCP endpoint: calls tools (evidence: `README.md`)
- MCP endpoint → Agent runtime: creates server
- Messaging user → Messaging channels: asks questions (evidence: `README.md`)
- Messaging channels → Agent runtime: routes requests
- Context templates → LLM provider: generates text (evidence: `cli/nao_core/templates/engine.py`)
- Live context review → Context repository: reads updates (evidence: `apps/backend/src/services/context-explorer-git/live-context.service.ts`)
