# labstack/pitot architecture

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

- Interactive diagram: https://gitdiagram.com/labstack/pitot
- Repository: https://github.com/labstack/pitot

## Overview

Pitot is a single-binary observability product: collectors send OTLP telemetry, which is stored locally and queried for exploration, dashboards, agent investigations, and alerts. The README documents the overall shared-query architecture; source excerpts and index references support selected internal relationships. Several implementation details are unsampled, so those links are omitted rather than inferred.

Main entry points: [`internal/query/exec.go`](https://github.com/labstack/pitot/blob/main/internal/query/exec.go) (Query execution), [`ui/host/src/app.tsx`](https://github.com/labstack/pitot/blob/main/ui/host/src/app.tsx) (React client), [`ui/host/src/dashboards/viz/service-map.tsx`](https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/viz/service-map.tsx) (Service map), [`ui/host/src/dashboards/api.ts`](https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/api.ts) (Dashboard client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingest and storage"]
  node_ingestion["OTLP ingest<br/>[server.go]"]
  node_telemetry[("Parquet telemetry<br/>[parquet.go]")]
  node_telemetry_store["Telemetry repository<br/>[repository.go]"]
end

subgraph group_query["Query and analysis"]
  node_query_engine["DuckDB engine<br/>[duck.go]"]
  node_query_executor["Query execution<br/>[exec.go]"]
  node_pitotql["PitotQL parser<br/>[parser.go]"]
  node_observability["Observability service<br/>[service.go]"]
end

subgraph group_product["Product interfaces"]
  node_web_api["HTTP API<br/>[queries.go]"]
  node_web_client["React client<br/>[app.tsx]"]
  node_auth_ui["Browser authentication<br/>[auth.tsx]"]
  node_dashboards_api["Dashboard client API<br/>[api.ts]"]
  node_panel_types["Dashboard contracts<br/>[types.ts]"]
  node_panel_compile["Panel compilation<br/>[compile.ts]"]
  node_panel_analysis["Panel analysis<br/>[analysis.ts]"]
  node_panel_annotations["Panel annotations<br/>[annotations.ts]"]
  node_service_map["Service map<br/>[service-map.tsx]"]
  node_dashboard_service["Dashboard service<br/>[service.go]"]
end

subgraph group_automation["Agents and alerts"]
  node_agent_runtime["Investigation agent<br/>[runtime.go]"]
  node_mcp_server["MCP server<br/>[server.go]"]
  node_alert_engine["Alert evaluation<br/>[engine.go]"]
  node_intelligence["Anomaly detection<br/>[detector.go]"]
end

node_collector(("OTLP collector"))
node_browser(("Browser user"))
node_external_agent(("External MCP client"))

node_collector -->|"sends OTLP"| node_ingestion
node_ingestion -->|"commits telemetry"| node_telemetry
node_telemetry_store -->|"reads batches"| node_telemetry
node_query_engine -->|"queries telemetry"| node_telemetry
node_web_client -->|"gates access"| node_auth_ui
node_web_client -->|"uses dashboard API"| node_dashboards_api
node_dashboards_api -->|"authorizes requests"| node_auth_ui
node_dashboards_api -->|"uses contracts"| node_panel_types
node_service_map -->|"uses compilation"| node_panel_compile
node_service_map -->|"uses analysis"| node_panel_analysis
node_service_map -->|"uses annotations"| node_panel_annotations
node_browser -->|"uses interface"| node_web_client
node_web_client -->|"calls API"| node_web_api
node_web_api -->|"runs queries"| node_query_executor
node_pitotql -->|"supports query language"| node_query_executor
node_agent_runtime -->|"investigates telemetry"| node_query_executor
node_mcp_server -->|"shares query tools"| node_query_executor
node_external_agent -->|"connects over MCP"| node_mcp_server
node_alert_engine -->|"evaluates query results"| node_query_engine
node_alert_engine -->|"uses detection"| node_intelligence
node_dashboard_service -->|"validates dashboards"| node_query_executor

click node_ingestion "https://github.com/labstack/pitot/blob/main/internal/ingest/server.go"
click node_telemetry "https://github.com/labstack/pitot/blob/main/internal/telemetry/parquet.go"
click node_telemetry_store "https://github.com/labstack/pitot/blob/main/internal/telemetry/store/repository.go"
click node_query_engine "https://github.com/labstack/pitot/blob/main/internal/engine/duck.go"
click node_query_executor "https://github.com/labstack/pitot/blob/main/internal/query/exec.go"
click node_pitotql "https://github.com/labstack/pitot/blob/main/internal/pitotql/parser.go"
click node_observability "https://github.com/labstack/pitot/blob/main/internal/observability/service.go"
click node_web_api "https://github.com/labstack/pitot/blob/main/internal/api/queries.go"
click node_web_client "https://github.com/labstack/pitot/blob/main/ui/host/src/app.tsx"
click node_auth_ui "https://github.com/labstack/pitot/blob/main/ui/host/src/auth.tsx"
click node_dashboards_api "https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/api.ts"
click node_panel_types "https://github.com/labstack/pitot/blob/main/ui/panels/types.ts"
click node_panel_compile "https://github.com/labstack/pitot/blob/main/ui/panels/compile.ts"
click node_panel_analysis "https://github.com/labstack/pitot/blob/main/ui/panels/analysis.ts"
click node_panel_annotations "https://github.com/labstack/pitot/blob/main/ui/panels/annotations.ts"
click node_service_map "https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/viz/service-map.tsx"
click node_dashboard_service "https://github.com/labstack/pitot/blob/main/internal/dashboard/service.go"
click node_agent_runtime "https://github.com/labstack/pitot/blob/main/internal/agent/runtime.go"
click node_mcp_server "https://github.com/labstack/pitot/blob/main/internal/mcp/server.go"
click node_alert_engine "https://github.com/labstack/pitot/blob/main/internal/alert/engine.go"
click node_intelligence "https://github.com/labstack/pitot/blob/main/internal/intelligence/detector.go"

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_ingestion,node_telemetry,node_telemetry_store,node_browser,node_external_agent toneBlue
class node_query_engine,node_query_executor,node_pitotql,node_observability toneAmber
class node_web_api,node_web_client,node_auth_ui,node_dashboards_api,node_panel_types,node_panel_compile,node_panel_analysis,node_panel_annotations,node_service_map,node_dashboard_service toneMint
class node_agent_runtime,node_mcp_server,node_alert_engine,node_intelligence toneRose
class node_collector toneIndigo
```

## Components

### Ingest and storage

- [OTLP ingest](https://github.com/labstack/pitot/blob/main/internal/ingest/server.go): `internal/ingest/server.go`
- [Parquet telemetry](https://github.com/labstack/pitot/blob/main/internal/telemetry/parquet.go): `internal/telemetry/parquet.go`
- [Telemetry repository](https://github.com/labstack/pitot/blob/main/internal/telemetry/store/repository.go): `internal/telemetry/store/repository.go`

### Query and analysis

- [DuckDB engine](https://github.com/labstack/pitot/blob/main/internal/engine/duck.go): `internal/engine/duck.go`
- [Query execution](https://github.com/labstack/pitot/blob/main/internal/query/exec.go): `internal/query/exec.go`
- [PitotQL parser](https://github.com/labstack/pitot/blob/main/internal/pitotql/parser.go): `internal/pitotql/parser.go`
- [Observability service](https://github.com/labstack/pitot/blob/main/internal/observability/service.go): `internal/observability/service.go`

### Product interfaces

- [HTTP API](https://github.com/labstack/pitot/blob/main/internal/api/queries.go): `internal/api/queries.go`
- [React client](https://github.com/labstack/pitot/blob/main/ui/host/src/app.tsx): `ui/host/src/app.tsx`
- [Browser authentication](https://github.com/labstack/pitot/blob/main/ui/host/src/auth.tsx): `ui/host/src/auth.tsx`
- [Dashboard client API](https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/api.ts): `ui/host/src/dashboards/api.ts`
- [Dashboard contracts](https://github.com/labstack/pitot/blob/main/ui/panels/types.ts): `ui/panels/types.ts`
- [Panel compilation](https://github.com/labstack/pitot/blob/main/ui/panels/compile.ts): `ui/panels/compile.ts`
- [Panel analysis](https://github.com/labstack/pitot/blob/main/ui/panels/analysis.ts): `ui/panels/analysis.ts`
- [Panel annotations](https://github.com/labstack/pitot/blob/main/ui/panels/annotations.ts): `ui/panels/annotations.ts`
- [Service map](https://github.com/labstack/pitot/blob/main/ui/host/src/dashboards/viz/service-map.tsx): `ui/host/src/dashboards/viz/service-map.tsx`
- [Dashboard service](https://github.com/labstack/pitot/blob/main/internal/dashboard/service.go): `internal/dashboard/service.go`

### Agents and alerts

- [Investigation agent](https://github.com/labstack/pitot/blob/main/internal/agent/runtime.go): `internal/agent/runtime.go`
- [MCP server](https://github.com/labstack/pitot/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [Alert evaluation](https://github.com/labstack/pitot/blob/main/internal/alert/engine.go): `internal/alert/engine.go`
- [Anomaly detection](https://github.com/labstack/pitot/blob/main/internal/intelligence/detector.go): `internal/intelligence/detector.go`

### Other components

- **OTLP collector**
- **Browser user**
- **External MCP client**

## Connections

- OTLP collector → OTLP ingest: sends OTLP (evidence: `README.md`)
- OTLP ingest → Parquet telemetry: commits telemetry (evidence: `README.md`)
- Telemetry repository → Parquet telemetry: reads batches (evidence: `internal/telemetry/store/repository.go`)
- DuckDB engine → Parquet telemetry: queries telemetry (evidence: `README.md`)
- React client → Browser authentication: gates access (evidence: `ui/host/src/app.tsx`)
- React client → Dashboard client API: uses dashboard API (evidence: `ui/host/src/app.tsx`)
- Dashboard client API → Browser authentication: authorizes requests (evidence: `ui/host/src/dashboards/api.ts`)
- Dashboard client API → Dashboard contracts: uses contracts (evidence: `ui/host/src/dashboards/api.ts`)
- Service map → Panel compilation: uses compilation (evidence: `ui/host/src/dashboards/viz/service-map.tsx`)
- Service map → Panel analysis: uses analysis (evidence: `ui/host/src/dashboards/viz/service-map.tsx`)
- Service map → Panel annotations: uses annotations (evidence: `ui/host/src/dashboards/viz/service-map.tsx`)
- Browser user → React client: uses interface (evidence: `README.md`)
- React client → HTTP API: calls API
- HTTP API → Query execution: runs queries (evidence: `README.md`)
- PitotQL parser → Query execution: supports query language (evidence: `internal/pitotql/parser.go`)
- Investigation agent → Query execution: investigates telemetry (evidence: `README.md`)
- MCP server → Query execution: shares query tools (evidence: `README.md`)
- External MCP client → MCP server: connects over MCP (evidence: `README.md`)
- Alert evaluation → DuckDB engine: evaluates query results (evidence: `internal/alert/engine.go`)
- Alert evaluation → Anomaly detection: uses detection (evidence: `internal/alert/engine.go`)
- Dashboard service → Query execution: validates dashboards (evidence: `internal/dashboard/service.go`)
