# avamingli/pg_dash architecture

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

- Interactive diagram: https://gitdiagram.com/avamingli/pg_dash
- Repository: https://github.com/avamingli/pg_dash

## Overview

PG Dash is a Go backend and React dashboard for monitoring PostgreSQL and WarehousePG clusters. The principal workflow is: an operator opens a dashboard page, the frontend requests metrics or feature data from the backend, and the backend collects or queries PostgreSQL and host state before returning results; live metrics also arrive over WebSocket. The graph preserves documented query analysis, history, recommendations, alerts, cluster features, and plan watch/replay. Unsampled feature implementations are represented by their exact source directories; edges are limited to visible wiring or README-documented relationships.

Main entry points: [`backend/internal/monitor/aggregator.go`](https://github.com/avamingli/pg_dash/blob/master/backend/internal/monitor/aggregator.go) (Metrics Aggregator), [`backend/cmd/server/main.go`](https://github.com/avamingli/pg_dash/blob/master/backend/cmd/server/main.go) (HTTP Server), [`backend/internal/handler`](https://github.com/avamingli/pg_dash/tree/master/backend/internal/handler) (API Handlers), [`frontend/src/pages`](https://github.com/avamingli/pg_dash/tree/master/frontend/src/pages) (Dashboard Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app["React App<br/>[App.tsx]"]
  node_pages["Dashboard Pages"]
  node_api_client["API Client<br/>[api.ts]"]
  node_metrics_context["Metrics Context<br/>[MetricsContext.tsx]"]
  node_websocket_hook["WebSocket Hook<br/>[useWebSocket.ts]"]
  node_plan_watch["Live Plan Watch"]
  node_plan_viewer["Plan Viewer<br/>[PlanViewer.tsx]"]
  node_replay["Plan Replay<br/>[replayEngine.ts]"]
end

subgraph group_api["API and Features"]
  node_server["HTTP Server<br/>[main.go]"]
  node_handlers["API Handlers"]
  node_connection["Connection Manager<br/>[connection.go]"]
end

subgraph group_monitoring["Monitoring"]
  node_aggregator["Metrics Aggregator<br/>[aggregator.go]"]
  node_pg_collector["PG Collectors"]
  node_os_collector["OS Collector<br/>[collector.go]"]
  node_alert_engine["Alert Engine<br/>[engine.go]"]
  node_websocket_hub["WebSocket Hub<br/>[hub.go]"]
  node_snapshot_store[("Snapshot Store<br/>[snapshot.go]")]
end

subgraph group_analysis["Query Analysis"]
  node_query_endpoints["SQL Editor Endpoints<br/>[query.go]"]
  node_query_sql["Query Definitions"]
  node_history[("Query History<br/>[history.go]")]
  node_recommendations["Health Scanner<br/>[scanner.go]"]
end

node_operator(("Operator"))
node_postgres[("PostgreSQL")]
node_host_os(("Host System"))
node_whpg_extension(("Plan Extension"))

node_operator -->|"uses"| node_app
node_app -->|"routes to"| node_pages
node_app -->|"provides"| node_metrics_context
node_pages -.->|"requests data"| node_api_client
node_api_client -->|"REST requests"| node_server
node_metrics_context -.->|"receives updates"| node_websocket_hook
node_websocket_hook -->|"WebSocket"| node_server
node_pages -->|"offers watch"| node_plan_watch
node_plan_watch -->|"renders plans"| node_plan_viewer
node_pages -->|"replays runs"| node_replay
node_server -->|"registers routes"| node_handlers
node_server -->|"starts collection"| node_aggregator
node_server -->|"creates hub"| node_websocket_hub
node_handlers -->|"uses pools"| node_connection
node_handlers -->|"routes SQL"| node_query_endpoints
node_query_endpoints -->|"uses statements"| node_query_sql
node_query_endpoints -->|"executes SQL"| node_postgres
node_connection -->|"connects"| node_postgres
node_aggregator -->|"collects metrics"| node_pg_collector
node_aggregator -->|"collects host stats"| node_os_collector
node_pg_collector -.->|"reads statistics"| node_postgres
node_os_collector -.->|"reads resources"| node_host_os
node_aggregator -->|"evaluates snapshots"| node_alert_engine
node_aggregator -->|"broadcasts metrics"| node_websocket_hub
node_aggregator -->|"records snapshots"| node_snapshot_store
node_handlers -.->|"exposes scans"| node_recommendations
node_recommendations -->|"uses checks"| node_query_sql
node_recommendations -.->|"scans database"| node_postgres
node_history -->|"stores history"| node_postgres
node_handlers -.->|"serves history"| node_history
node_whpg_extension -->|"provides live plans"| node_plan_watch
node_plan_watch -->|"watches queries"| node_server

click node_app "https://github.com/avamingli/pg_dash/blob/master/frontend/src/App.tsx"
click node_pages "https://github.com/avamingli/pg_dash/tree/master/frontend/src/pages"
click node_api_client "https://github.com/avamingli/pg_dash/blob/master/frontend/src/lib/api.ts"
click node_metrics_context "https://github.com/avamingli/pg_dash/blob/master/frontend/src/contexts/MetricsContext.tsx"
click node_websocket_hook "https://github.com/avamingli/pg_dash/blob/master/frontend/src/hooks/useWebSocket.ts"
click node_plan_watch "https://github.com/avamingli/pg_dash/blob/master/frontend/src/components/QueryWatchPanel.tsx"
click node_plan_viewer "https://github.com/avamingli/pg_dash/blob/master/frontend/src/components/PlanViewer.tsx"
click node_replay "https://github.com/avamingli/pg_dash/blob/master/frontend/src/lib/replayEngine.ts"
click node_server "https://github.com/avamingli/pg_dash/blob/master/backend/cmd/server/main.go"
click node_handlers "https://github.com/avamingli/pg_dash/tree/master/backend/internal/handler"
click node_connection "https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/connection.go"
click node_query_endpoints "https://github.com/avamingli/pg_dash/blob/master/backend/internal/handler/query.go"
click node_query_sql "https://github.com/avamingli/pg_dash/tree/master/backend/internal/query"
click node_history "https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/history.go"
click node_recommendations "https://github.com/avamingli/pg_dash/blob/master/backend/internal/recommend/scanner.go"
click node_aggregator "https://github.com/avamingli/pg_dash/blob/master/backend/internal/monitor/aggregator.go"
click node_pg_collector "https://github.com/avamingli/pg_dash/tree/master/backend/internal/monitor/pg"
click node_os_collector "https://github.com/avamingli/pg_dash/blob/master/backend/internal/monitor/os/collector.go"
click node_alert_engine "https://github.com/avamingli/pg_dash/blob/master/backend/internal/alert/engine.go"
click node_websocket_hub "https://github.com/avamingli/pg_dash/blob/master/backend/internal/ws/hub.go"
click node_snapshot_store "https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/snapshot.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_app,node_pages,node_api_client,node_metrics_context,node_websocket_hook,node_plan_watch,node_plan_viewer,node_replay toneBlue
class node_server,node_handlers,node_connection,node_postgres toneAmber
class node_aggregator,node_pg_collector,node_os_collector,node_alert_engine,node_websocket_hub,node_snapshot_store toneMint
class node_query_endpoints,node_query_sql,node_history,node_recommendations toneRose
class node_operator,node_host_os,node_whpg_extension toneIndigo
```

## Components

### Dashboard

- [React App](https://github.com/avamingli/pg_dash/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard Pages](https://github.com/avamingli/pg_dash/tree/master/frontend/src/pages): `frontend/src/pages`
- [API Client](https://github.com/avamingli/pg_dash/blob/master/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Metrics Context](https://github.com/avamingli/pg_dash/blob/master/frontend/src/contexts/MetricsContext.tsx): `frontend/src/contexts/MetricsContext.tsx`
- [WebSocket Hook](https://github.com/avamingli/pg_dash/blob/master/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`
- [Live Plan Watch](https://github.com/avamingli/pg_dash/blob/master/frontend/src/components/QueryWatchPanel.tsx): `frontend/src/components/QueryWatchPanel.tsx`
- [Plan Viewer](https://github.com/avamingli/pg_dash/blob/master/frontend/src/components/PlanViewer.tsx): `frontend/src/components/PlanViewer.tsx`
- [Plan Replay](https://github.com/avamingli/pg_dash/blob/master/frontend/src/lib/replayEngine.ts): `frontend/src/lib/replayEngine.ts`

### API and Features

- [HTTP Server](https://github.com/avamingli/pg_dash/blob/master/backend/cmd/server/main.go): `backend/cmd/server/main.go`
- [API Handlers](https://github.com/avamingli/pg_dash/tree/master/backend/internal/handler): `backend/internal/handler`
- [Connection Manager](https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/connection.go): `backend/internal/service/connection.go`

### Monitoring

- [Metrics Aggregator](https://github.com/avamingli/pg_dash/blob/master/backend/internal/monitor/aggregator.go): `backend/internal/monitor/aggregator.go`
- [PG Collectors](https://github.com/avamingli/pg_dash/tree/master/backend/internal/monitor/pg): `backend/internal/monitor/pg`
- [OS Collector](https://github.com/avamingli/pg_dash/blob/master/backend/internal/monitor/os/collector.go): `backend/internal/monitor/os/collector.go`
- [Alert Engine](https://github.com/avamingli/pg_dash/blob/master/backend/internal/alert/engine.go): `backend/internal/alert/engine.go`
- [WebSocket Hub](https://github.com/avamingli/pg_dash/blob/master/backend/internal/ws/hub.go): `backend/internal/ws/hub.go`
- [Snapshot Store](https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/snapshot.go): `backend/internal/service/snapshot.go`

### Query Analysis

- [SQL Editor Endpoints](https://github.com/avamingli/pg_dash/blob/master/backend/internal/handler/query.go): `backend/internal/handler/query.go`
- [Query Definitions](https://github.com/avamingli/pg_dash/tree/master/backend/internal/query): `backend/internal/query`
- [Query History](https://github.com/avamingli/pg_dash/blob/master/backend/internal/service/history.go): `backend/internal/service/history.go`
- [Health Scanner](https://github.com/avamingli/pg_dash/blob/master/backend/internal/recommend/scanner.go): `backend/internal/recommend/scanner.go`

### Other components

- **Operator**
- **PostgreSQL**
- **Host System**
- **Plan Extension**

## Connections

- Operator → React App: uses
- React App → Dashboard Pages: routes to (evidence: `frontend/src/App.tsx`)
- React App → Metrics Context: provides (evidence: `frontend/src/App.tsx`)
- Dashboard Pages → API Client: requests data
- API Client → HTTP Server: REST requests
- Metrics Context → WebSocket Hook: receives updates
- WebSocket Hook → HTTP Server: WebSocket
- Dashboard Pages → Live Plan Watch: offers watch
- Live Plan Watch → Plan Viewer: renders plans (evidence: `frontend/src/components/QueryWatchPanel.tsx`)
- Dashboard Pages → Plan Replay: replays runs
- HTTP Server → API Handlers: registers routes (evidence: `backend/cmd/server/main.go`)
- HTTP Server → Metrics Aggregator: starts collection (evidence: `backend/cmd/server/main.go`)
- HTTP Server → WebSocket Hub: creates hub (evidence: `backend/cmd/server/main.go`)
- API Handlers → Connection Manager: uses pools (evidence: `backend/internal/handler/database.go`)
- API Handlers → SQL Editor Endpoints: routes SQL
- SQL Editor Endpoints → Query Definitions: uses statements (evidence: `backend/internal/handler/query.go`)
- SQL Editor Endpoints → PostgreSQL: executes SQL (evidence: `backend/internal/handler/query.go`)
- Connection Manager → PostgreSQL: connects
- Metrics Aggregator → PG Collectors: collects metrics (evidence: `backend/internal/monitor/aggregator.go`)
- Metrics Aggregator → OS Collector: collects host stats (evidence: `backend/internal/monitor/aggregator.go`)
- PG Collectors → PostgreSQL: reads statistics
- OS Collector → Host System: reads resources
- Metrics Aggregator → Alert Engine: evaluates snapshots (evidence: `backend/internal/monitor/aggregator.go`)
- Metrics Aggregator → WebSocket Hub: broadcasts metrics (evidence: `backend/internal/monitor/aggregator.go`)
- Metrics Aggregator → Snapshot Store: records snapshots
- API Handlers → Health Scanner: exposes scans
- Health Scanner → Query Definitions: uses checks (evidence: `backend/internal/recommend/scanner.go`)
- Health Scanner → PostgreSQL: scans database
- Query History → PostgreSQL: stores history (evidence: `backend/internal/service/history.go`)
- API Handlers → Query History: serves history
- Plan Extension → Live Plan Watch: provides live plans
- Live Plan Watch → HTTP Server: watches queries
