# timescale/pg-aiguide architecture

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

- Interactive diagram: https://gitdiagram.com/timescale/pg-aiguide
- Repository: https://github.com/timescale/pg-aiguide

## Overview

pg-aiguide gives coding agents PostgreSQL expertise through MCP documentation search and installable skills. The main runtime path is an agent request entering the MCP server, dispatching a search or skill tool, and returning documentation results or curated guidance. A separate ingestion path scrapes PostgreSQL, PostGIS, and Tiger/Timescale documentation, chunks and embeds it, then stores searchable records. Source excerpts establish core call relationships; skill availability and remote MCP usage are documented in the README, while some ingestion-stage wiring is supported only by the SOURCE INDEX.

Main entry points: [`ingest/document_importer.py`](https://github.com/timescale/pg-aiguide/blob/main/ingest/document_importer.py) (Page Importer), [`src/apis/searchDocs.ts`](https://github.com/timescale/pg-aiguide/blob/main/src/apis/searchDocs.ts) (Search Tool), [`src/apis/index.ts`](https://github.com/timescale/pg-aiguide/blob/main/src/apis/index.ts) (Skill Tool), [`src/httpServer.ts`](https://github.com/timescale/pg-aiguide/blob/main/src/httpServer.ts) (HTTP Transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_entry["Entrypoint<br/>[index.ts]"]
  node_http["HTTP Transport<br/>[httpServer.ts]"]
  node_stdio["Stdio Transport<br/>[stdio.ts]"]
  node_context["Server Context<br/>[serverInfo.ts]"]
end

subgraph group_search["Documentation Search"]
  node_api["Tool Registry<br/>[index.ts]"]
  node_searchtool["Search Tool<br/>[searchDocs.ts]"]
  node_rows["Chunk Query<br/>[getDocChunkRows.ts]"]
  node_fusion["Rank Fusion<br/>[rrf.ts]"]
end

subgraph group_ingest["Documentation Ingestion"]
  node_pg_crawl["Postgres Import<br/>[postgres_docs.py]"]
  node_postgis_crawl["PostGIS Import<br/>[postgis_docs.py]"]
  node_tiger_crawl["Tiger Docs Scraper<br/>[tiger_docs.py]"]
  node_clean["HTML Conversion<br/>[beautiful_soup.py]"]
  node_importer["Page Importer"]
  node_chunking["Markdown Chunking<br/>[chunking.py]"]
  node_models["Page And Chunk Models<br/>[models.py]"]
end

subgraph group_skills["Agent Skills"]
  node_skilltool["Skill Tool<br/>[index.ts]"]
  node_skill_library["Postgres Skill Library"]
  node_schema_skill["Schema Exploration"]
  node_specialist_skills["Specialist Skills"]
end

node_agent(("Coding Agent"))
node_embedding_api["Embedding API"]
node_database[("Documentation Store")]
node_operator(("Ingest Operator"))

node_agent -->|"sends requests"| node_http
node_agent -->|"uses tools"| node_stdio
node_entry -->|"launches transport"| node_http
node_entry -->|"launches transport"| node_stdio
node_http -->|"registers tools"| node_api
node_stdio -->|"registers tools"| node_api
node_api -->|"registers search"| node_searchtool
node_http -->|"registers prompts"| node_skilltool
node_stdio -->|"registers prompts"| node_skilltool
node_skilltool -->|"retrieves skills"| node_skill_library
node_skilltool -->|"retrieves skills"| node_schema_skill
node_skilltool -->|"retrieves skills"| node_specialist_skills
node_searchtool -->|"queries chunks"| node_rows
node_searchtool -->|"fuses rankings"| node_fusion
node_searchtool -->|"embeds query"| node_embedding_api
node_rows -->|"queries records"| node_database
node_searchtool -->|"uses pool context"| node_context
node_operator -.->|"starts import"| node_pg_crawl
node_operator -.->|"starts import"| node_postgis_crawl
node_operator -.->|"starts scrape"| node_tiger_crawl
node_pg_crawl -->|"uses importer"| node_importer
node_postgis_crawl -->|"uses importer"| node_importer
node_pg_crawl -->|"converts HTML"| node_clean
node_postgis_crawl -->|"converts HTML"| node_clean
node_importer -->|"chunks markdown"| node_chunking
node_importer -->|"uses page models"| node_models
node_importer -->|"requests embeddings"| node_embedding_api
node_importer -->|"writes chunks"| node_database
node_tiger_crawl -->|"stores scraped docs"| node_database
node_tiger_crawl -->|"uses HTML utilities"| node_clean

click node_entry "https://github.com/timescale/pg-aiguide/blob/main/src/index.ts"
click node_http "https://github.com/timescale/pg-aiguide/blob/main/src/httpServer.ts"
click node_stdio "https://github.com/timescale/pg-aiguide/blob/main/src/stdio.ts"
click node_context "https://github.com/timescale/pg-aiguide/blob/main/src/serverInfo.ts"
click node_api "https://github.com/timescale/pg-aiguide/blob/main/src/apis/index.ts"
click node_searchtool "https://github.com/timescale/pg-aiguide/blob/main/src/apis/searchDocs.ts"
click node_rows "https://github.com/timescale/pg-aiguide/blob/main/src/util/getDocChunkRows.ts"
click node_fusion "https://github.com/timescale/pg-aiguide/blob/main/src/util/rrf.ts"
click node_pg_crawl "https://github.com/timescale/pg-aiguide/blob/main/ingest/postgres_docs.py"
click node_postgis_crawl "https://github.com/timescale/pg-aiguide/blob/main/ingest/postgis_docs.py"
click node_tiger_crawl "https://github.com/timescale/pg-aiguide/blob/main/ingest/tiger_docs.py"
click node_clean "https://github.com/timescale/pg-aiguide/blob/main/ingest/utils/beautiful_soup.py"
click node_importer "https://github.com/timescale/pg-aiguide/blob/main/ingest/document_importer.py"
click node_chunking "https://github.com/timescale/pg-aiguide/blob/main/ingest/utils/chunking.py"
click node_models "https://github.com/timescale/pg-aiguide/blob/main/ingest/models.py"
click node_skilltool "https://github.com/timescale/pg-aiguide/blob/main/src/apis/index.ts"
click node_skill_library "https://github.com/timescale/pg-aiguide/tree/main/skills/postgres"
click node_schema_skill "https://github.com/timescale/pg-aiguide/tree/main/skills/schema-exploration"
click node_specialist_skills "https://github.com/timescale/pg-aiguide/tree/main/skills/design-postgres-tables"

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_entry,node_http,node_stdio,node_context toneBlue
class node_api,node_searchtool,node_rows,node_fusion,node_database toneAmber
class node_pg_crawl,node_postgis_crawl,node_tiger_crawl,node_clean,node_importer,node_chunking,node_models,node_embedding_api toneMint
class node_skilltool,node_skill_library,node_schema_skill,node_specialist_skills toneRose
class node_agent,node_operator toneIndigo
```

## Components

### MCP Server

- [Entrypoint](https://github.com/timescale/pg-aiguide/blob/main/src/index.ts): `src/index.ts`
- [HTTP Transport](https://github.com/timescale/pg-aiguide/blob/main/src/httpServer.ts): `src/httpServer.ts`
- [Stdio Transport](https://github.com/timescale/pg-aiguide/blob/main/src/stdio.ts): `src/stdio.ts`
- [Server Context](https://github.com/timescale/pg-aiguide/blob/main/src/serverInfo.ts): `src/serverInfo.ts`

### Documentation Search

- [Tool Registry](https://github.com/timescale/pg-aiguide/blob/main/src/apis/index.ts): `src/apis/index.ts`
- [Search Tool](https://github.com/timescale/pg-aiguide/blob/main/src/apis/searchDocs.ts): `src/apis/searchDocs.ts`
- [Chunk Query](https://github.com/timescale/pg-aiguide/blob/main/src/util/getDocChunkRows.ts): `src/util/getDocChunkRows.ts`
- [Rank Fusion](https://github.com/timescale/pg-aiguide/blob/main/src/util/rrf.ts): `src/util/rrf.ts`

### Documentation Ingestion

- [Postgres Import](https://github.com/timescale/pg-aiguide/blob/main/ingest/postgres_docs.py): `ingest/postgres_docs.py`
- [PostGIS Import](https://github.com/timescale/pg-aiguide/blob/main/ingest/postgis_docs.py): `ingest/postgis_docs.py`
- [Tiger Docs Scraper](https://github.com/timescale/pg-aiguide/blob/main/ingest/tiger_docs.py): `ingest/tiger_docs.py`
- [HTML Conversion](https://github.com/timescale/pg-aiguide/blob/main/ingest/utils/beautiful_soup.py): `ingest/utils/beautiful_soup.py`
- [Page Importer](https://github.com/timescale/pg-aiguide/blob/main/ingest/document_importer.py): `ingest/document_importer.py`
- [Markdown Chunking](https://github.com/timescale/pg-aiguide/blob/main/ingest/utils/chunking.py): `ingest/utils/chunking.py`
- [Page And Chunk Models](https://github.com/timescale/pg-aiguide/blob/main/ingest/models.py): `ingest/models.py`

### Agent Skills

- [Skill Tool](https://github.com/timescale/pg-aiguide/blob/main/src/apis/index.ts): `src/apis/index.ts`
- [Postgres Skill Library](https://github.com/timescale/pg-aiguide/tree/main/skills/postgres): `skills/postgres`
- [Schema Exploration](https://github.com/timescale/pg-aiguide/tree/main/skills/schema-exploration): `skills/schema-exploration`
- [Specialist Skills](https://github.com/timescale/pg-aiguide/tree/main/skills/design-postgres-tables): `skills/design-postgres-tables`

### Other components

- **Coding Agent**
- **Embedding API**
- **Documentation Store**
- **Ingest Operator**

## Connections

- Coding Agent → HTTP Transport: sends requests (evidence: `README.md`)
- Coding Agent → Stdio Transport: uses tools (evidence: `README.md`)
- Entrypoint → HTTP Transport: launches transport (evidence: `src/index.ts`)
- Entrypoint → Stdio Transport: launches transport (evidence: `src/index.ts`)
- HTTP Transport → Tool Registry: registers tools (evidence: `src/httpServer.ts`)
- Stdio Transport → Tool Registry: registers tools (evidence: `src/stdio.ts`)
- Tool Registry → Search Tool: registers search (evidence: `src/apis/index.ts`)
- HTTP Transport → Skill Tool: registers prompts (evidence: `src/httpServer.ts`)
- Stdio Transport → Skill Tool: registers prompts (evidence: `src/stdio.ts`)
- Skill Tool → Postgres Skill Library: retrieves skills (evidence: `README.md`)
- Skill Tool → Schema Exploration: retrieves skills (evidence: `README.md`)
- Skill Tool → Specialist Skills: retrieves skills (evidence: `README.md`)
- Search Tool → Chunk Query: queries chunks (evidence: `src/apis/searchDocs.ts`)
- Search Tool → Rank Fusion: fuses rankings (evidence: `src/apis/searchDocs.ts`)
- Search Tool → Embedding API: embeds query (evidence: `src/apis/searchDocs.ts`)
- Chunk Query → Documentation Store: queries records (evidence: `src/util/getDocChunkRows.ts`)
- Search Tool → Server Context: uses pool context (evidence: `src/apis/searchDocs.ts`)
- Ingest Operator → Postgres Import: starts import
- Ingest Operator → PostGIS Import: starts import
- Ingest Operator → Tiger Docs Scraper: starts scrape
- Postgres Import → Page Importer: uses importer (evidence: `ingest/postgres_docs.py`)
- PostGIS Import → Page Importer: uses importer (evidence: `ingest/postgis_docs.py`)
- Postgres Import → HTML Conversion: converts HTML (evidence: `ingest/postgres_docs.py`)
- PostGIS Import → HTML Conversion: converts HTML (evidence: `ingest/postgis_docs.py`)
- Page Importer → Markdown Chunking: chunks markdown (evidence: `ingest/document_importer.py`)
- Page Importer → Page And Chunk Models: uses page models (evidence: `ingest/document_importer.py`)
- Page Importer → Embedding API: requests embeddings (evidence: `ingest/document_importer.py`)
- Page Importer → Documentation Store: writes chunks (evidence: `ingest/document_importer.py`)
- Tiger Docs Scraper → Documentation Store: stores scraped docs (evidence: `ingest/tiger_docs.py`)
- Tiger Docs Scraper → HTML Conversion: uses HTML utilities (evidence: `ingest/tiger_docs.py`)
