# clickhouse/clickstack architecture

> Architecture diagram of the GitHub repository clickhouse/clickstack, 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/clickhouse/clickstack
- Repository: https://github.com/clickhouse/clickstack

## Overview

ClickStack is an observability product for searching and visualizing logs, metrics, traces, and session replays over ClickHouse. Engineers ingest telemetry, discover sources, investigate events and traces, and use charts, dashboards, and alerts to monitor systems. The web app, API, MCP interface, and terminal CLI provide distinct ways to work with this data. The graph preserves documented product capabilities and sampled query/MCP relationships; many UI routes, ingestion internals, and persistence connections were not shown, so those links are omitted.

Main entry points: [`packages/api/src/mcp/mcpServer.ts`](https://github.com/clickhouse/clickstack/blob/main/packages/api/src/mcp/mcpServer.ts) (MCP server), [`packages/app/pages`](https://github.com/clickhouse/clickstack/tree/main/packages/app/pages) (Web application), [`packages/common-utils/src`](https://github.com/clickhouse/clickstack/tree/main/packages/common-utils/src) (Query and schema utilities), [`packages/app/src/hooks/useOffsetPaginatedQuery.tsx`](https://github.com/clickhouse/clickstack/blob/main/packages/app/src/hooks/useOffsetPaginatedQuery.tsx) (Paged chart queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web investigation"]
  node_webapp["Web application"]
  node_time["Time selection<br/>[timeQuery.ts]"]
  node_metadata["Metadata lookup<br/>[useMetadata.tsx]"]
  node_pagedquery["Paged chart queries"]
  node_serviceviews["Service dashboards"]
end

subgraph group_api["API services"]
  node_api["Application API<br/>[server.ts]"]
  node_routes["API routes"]
  node_controllers["Domain controllers"]
  node_alerts["Alert evaluation"]
  node_timeseries["Prometheus queries"]
end

subgraph group_query["Query foundation"]
  node_common["Query and schema utilities"]
  node_queryparser["Search syntax parser<br/>[queryParser.ts]"]
end

subgraph group_mcp["Agent interface"]
  node_mcphttp["MCP HTTP endpoint<br/>[app.ts]"]
  node_mcpserver["MCP server<br/>[mcpServer.ts]"]
  node_mcpquery["Query tools"]
  node_mcpdash["Dashboard tools"]
  node_mcpsources["Source tools"]
  node_mcpother["Alert and trace tools"]
end

subgraph group_cli["Terminal interface"]
  node_cliapp["CLI interface<br/>[App.tsx]"]
  node_cliclient["CLI API client<br/>[client.ts]"]
  node_clievents["Event query builder<br/>[eventQuery.ts]"]
  node_clitiles["Dashboard tile queries<br/>[tileQuery.ts]"]
  node_keybindings["TUI keybindings<br/>[useKeybindings.ts]"]
end

node_engineer(("Engineer"))
node_telemetry(("Telemetry producers"))
node_clickhouse[("ClickHouse")]

node_engineer -->|"investigates in"| node_webapp
node_telemetry -.->|"stores telemetry"| node_clickhouse
node_webapp -->|"uses API"| node_api
node_webapp -.->|"sets time range"| node_time
node_pagedquery -->|"loads metadata"| node_metadata
node_pagedquery -->|"renders chart query"| node_common
node_serviceviews -.->|"supports APM views"| node_webapp
node_api -.->|"serves routes"| node_routes
node_routes -.->|"dispatches requests"| node_controllers
node_alerts -.->|"evaluates telemetry"| node_clickhouse
node_timeseries -->|"uses metadata and SQL"| node_common
node_engineer -->|"uses terminal"| node_cliapp
node_cliapp -->|"loads data"| node_cliclient
node_clievents -->|"renders event SQL"| node_common
node_clitiles -->|"queries chart config"| node_common
node_engineer -.->|"connects agent"| node_mcphttp
node_mcphttp -->|"creates server"| node_mcpserver
node_mcpserver -->|"registers tools"| node_mcpquery
node_mcpserver -->|"registers tools"| node_mcpdash
node_mcpserver -->|"registers tools"| node_mcpsources
node_mcpserver -->|"registers tools"| node_mcpother
node_mcpquery -.->|"queries observability data"| node_clickhouse

click node_webapp "https://github.com/clickhouse/clickstack/tree/main/packages/app/pages"
click node_time "https://github.com/clickhouse/clickstack/blob/main/packages/app/src/timeQuery.ts"
click node_metadata "https://github.com/clickhouse/clickstack/blob/main/packages/app/src/hooks/useMetadata.tsx"
click node_pagedquery "https://github.com/clickhouse/clickstack/blob/main/packages/app/src/hooks/useOffsetPaginatedQuery.tsx"
click node_serviceviews "https://github.com/clickhouse/clickstack/tree/main/packages/app/src/ServicesDashboardPage"
click node_api "https://github.com/clickhouse/clickstack/blob/main/packages/api/src/server.ts"
click node_routes "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/routers"
click node_controllers "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/controllers"
click node_alerts "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/tasks/checkAlerts"
click node_timeseries "https://github.com/clickhouse/clickstack/blob/main/packages/api/src/controllers/timeseriesEngine.ts"
click node_common "https://github.com/clickhouse/clickstack/tree/main/packages/common-utils/src"
click node_queryparser "https://github.com/clickhouse/clickstack/blob/main/packages/common-utils/src/queryParser.ts"
click node_mcphttp "https://github.com/clickhouse/clickstack/blob/main/packages/api/src/mcp/app.ts"
click node_mcpserver "https://github.com/clickhouse/clickstack/blob/main/packages/api/src/mcp/mcpServer.ts"
click node_mcpquery "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/query"
click node_mcpdash "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/dashboards"
click node_mcpsources "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/sources"
click node_mcpother "https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools"
click node_cliapp "https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/App.tsx"
click node_cliclient "https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/api/client.ts"
click node_clievents "https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/api/eventQuery.ts"
click node_clitiles "https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/shared/tileQuery.ts"
click node_keybindings "https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/components/EventViewer/useKeybindings.ts"

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_webapp,node_time,node_metadata,node_pagedquery,node_serviceviews toneBlue
class node_api,node_routes,node_controllers,node_alerts,node_timeseries,node_clickhouse toneAmber
class node_common,node_queryparser toneMint
class node_mcphttp,node_mcpserver,node_mcpquery,node_mcpdash,node_mcpsources,node_mcpother toneRose
class node_cliapp,node_cliclient,node_clievents,node_clitiles,node_keybindings,node_engineer,node_telemetry toneIndigo
```

## Components

### Web investigation

- [Web application](https://github.com/clickhouse/clickstack/tree/main/packages/app/pages): `packages/app/pages`
- [Time selection](https://github.com/clickhouse/clickstack/blob/main/packages/app/src/timeQuery.ts): `packages/app/src/timeQuery.ts`
- [Metadata lookup](https://github.com/clickhouse/clickstack/blob/main/packages/app/src/hooks/useMetadata.tsx): `packages/app/src/hooks/useMetadata.tsx`
- [Paged chart queries](https://github.com/clickhouse/clickstack/blob/main/packages/app/src/hooks/useOffsetPaginatedQuery.tsx): `packages/app/src/hooks/useOffsetPaginatedQuery.tsx`
- [Service dashboards](https://github.com/clickhouse/clickstack/tree/main/packages/app/src/ServicesDashboardPage): `packages/app/src/ServicesDashboardPage`

### API services

- [Application API](https://github.com/clickhouse/clickstack/blob/main/packages/api/src/server.ts): `packages/api/src/server.ts`
- [API routes](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/routers): `packages/api/src/routers`
- [Domain controllers](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/controllers): `packages/api/src/controllers`
- [Alert evaluation](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/tasks/checkAlerts): `packages/api/src/tasks/checkAlerts`
- [Prometheus queries](https://github.com/clickhouse/clickstack/blob/main/packages/api/src/controllers/timeseriesEngine.ts): `packages/api/src/controllers/timeseriesEngine.ts`

### Query foundation

- [Query and schema utilities](https://github.com/clickhouse/clickstack/tree/main/packages/common-utils/src): `packages/common-utils/src`
- [Search syntax parser](https://github.com/clickhouse/clickstack/blob/main/packages/common-utils/src/queryParser.ts): `packages/common-utils/src/queryParser.ts`

### Agent interface

- [MCP HTTP endpoint](https://github.com/clickhouse/clickstack/blob/main/packages/api/src/mcp/app.ts): `packages/api/src/mcp/app.ts`
- [MCP server](https://github.com/clickhouse/clickstack/blob/main/packages/api/src/mcp/mcpServer.ts): `packages/api/src/mcp/mcpServer.ts`
- [Query tools](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/query): `packages/api/src/mcp/tools/query`
- [Dashboard tools](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/dashboards): `packages/api/src/mcp/tools/dashboards`
- [Source tools](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools/sources): `packages/api/src/mcp/tools/sources`
- [Alert and trace tools](https://github.com/clickhouse/clickstack/tree/main/packages/api/src/mcp/tools): `packages/api/src/mcp/tools`

### Terminal interface

- [CLI interface](https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/App.tsx): `packages/cli/src/App.tsx`
- [CLI API client](https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/api/client.ts): `packages/cli/src/api/client.ts`
- [Event query builder](https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/api/eventQuery.ts): `packages/cli/src/api/eventQuery.ts`
- [Dashboard tile queries](https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/shared/tileQuery.ts): `packages/cli/src/shared/tileQuery.ts`
- [TUI keybindings](https://github.com/clickhouse/clickstack/blob/main/packages/cli/src/components/EventViewer/useKeybindings.ts): `packages/cli/src/components/EventViewer/useKeybindings.ts`

### Other components

- **Engineer**
- **Telemetry producers**
- **ClickHouse**

## Connections

- Engineer → Web application: investigates in (evidence: `README.md`)
- Telemetry producers → ClickHouse: stores telemetry
- Web application → Application API: uses API (evidence: `README.md`)
- Web application → Time selection: sets time range
- Paged chart queries → Metadata lookup: loads metadata (evidence: `packages/app/src/hooks/useOffsetPaginatedQuery.tsx`)
- Paged chart queries → Query and schema utilities: renders chart query (evidence: `packages/app/src/hooks/useOffsetPaginatedQuery.tsx`)
- Service dashboards → Web application: supports APM views
- Application API → API routes: serves routes
- API routes → Domain controllers: dispatches requests
- Alert evaluation → ClickHouse: evaluates telemetry
- Prometheus queries → Query and schema utilities: uses metadata and SQL (evidence: `packages/api/src/controllers/timeseriesEngine.ts`)
- Engineer → CLI interface: uses terminal (evidence: `README.md`)
- CLI interface → CLI API client: loads data (evidence: `packages/cli/src/App.tsx`)
- Event query builder → Query and schema utilities: renders event SQL (evidence: `packages/cli/src/api/eventQuery.ts`)
- Dashboard tile queries → Query and schema utilities: queries chart config (evidence: `packages/cli/src/shared/tileQuery.ts`)
- Engineer → MCP HTTP endpoint: connects agent
- MCP HTTP endpoint → MCP server: creates server (evidence: `packages/api/src/mcp/app.ts`)
- MCP server → Query tools: registers tools (evidence: `packages/api/src/mcp/mcpServer.ts`)
- MCP server → Dashboard tools: registers tools (evidence: `packages/api/src/mcp/mcpServer.ts`)
- MCP server → Source tools: registers tools (evidence: `packages/api/src/mcp/mcpServer.ts`)
- MCP server → Alert and trace tools: registers tools (evidence: `packages/api/src/mcp/mcpServer.ts`)
- Query tools → ClickHouse: queries observability data