# pgedge/pgedge-rag-server architecture

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

- Interactive diagram: https://gitdiagram.com/pgedge/pgedge-rag-server
- Repository: https://github.com/pgedge/pgedge-rag-server

## Overview

pgEdge RAG Server exposes a multi-pipeline HTTP API that retrieves PostgreSQL content and uses configurable language-model providers to generate answers, with optional streaming. Requests pass through identity checks before the selected pipeline performs hybrid vector/BM25 retrieval, optional reranking, context budgeting, and generation. Configuration, health, stats, and hot reload support the service lifecycle. The sampled source confirms the main request path and key components; some documented provider and API details are represented at subsystem level where implementation excerpts were not available.

Main entry points: [`internal/pipeline/orchestrator.go`](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/orchestrator.go) (RAG orchestrator), [`internal/pipeline/manager.go`](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/manager.go) (Pipeline manager), [`cmd/pgedge-rag-server/main.go`](https://github.com/pgedge/pgedge-rag-server/blob/main/cmd/pgedge-rag-server/main.go) (Server startup), [`internal/server/handlers.go`](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/handlers.go) (Request handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service runtime"]
  node_main["Server startup<br/>[main.go]"]
  node_http["HTTP server<br/>[server.go]"]
  node_routes["API routes<br/>[routes.go]"]
  node_handlers["Request handlers<br/>[handlers.go]"]
end

subgraph group_query["RAG query path"]
  node_manager["Pipeline manager<br/>[manager.go]"]
  node_orchestrator["RAG orchestrator<br/>[orchestrator.go]"]
  node_bm25["BM25 index<br/>[index.go]"]
  node_ragcontext["Prompt context<br/>[rag.go]"]
end

subgraph group_data["Corpus access"]
  node_dbpool["Database pool<br/>[pool.go]"]
  node_dbsearch["Corpus search<br/>[search.go]"]
end

subgraph group_integrations["External systems"]
  node_pg[("PostgreSQL + pgvector")]
  node_llmfactory["Provider factory<br/>[factory.go]"]
  node_llmproviders["Embedding and LLM providers"]
end

subgraph group_operations["Configuration and identity"]
  node_config["Config loader<br/>[loader.go]"]
  node_watcher["Config watcher<br/>[watcher.go]"]
  node_identity["Caller identity<br/>[identity.go]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_http
node_main -->|"loads config"| node_config
node_main -->|"creates pipelines"| node_manager
node_main -->|"starts server"| node_http
node_main -->|"watches config"| node_watcher
node_watcher -->|"triggers reload"| node_config
node_http -->|"registers routes"| node_routes
node_routes -->|"dispatches requests"| node_handlers
node_handlers -->|"extracts identity"| node_identity
node_handlers -->|"selects pipeline"| node_manager
node_handlers -->|"executes query"| node_orchestrator
node_manager -->|"creates pools"| node_dbpool
node_manager -->|"creates clients"| node_llmfactory
node_manager -->|"configures pipeline"| node_orchestrator
node_orchestrator -->|"searches corpus"| node_dbsearch
node_orchestrator -->|"fetches BM25 docs"| node_dbsearch
node_dbsearch -->|"uses pool"| node_dbpool
node_dbpool -->|"queries"| node_pg
node_orchestrator -->|"ranks text"| node_bm25
node_orchestrator -->|"formats context"| node_ragcontext
node_orchestrator -->|"embeds and generates"| node_llmproviders
node_llmfactory -->|"constructs clients"| node_llmproviders
node_orchestrator -.->|"reranks optionally"| node_llmproviders

click node_main "https://github.com/pgedge/pgedge-rag-server/blob/main/cmd/pgedge-rag-server/main.go"
click node_http "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/server.go"
click node_routes "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/routes.go"
click node_handlers "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/handlers.go"
click node_manager "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/manager.go"
click node_orchestrator "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/orchestrator.go"
click node_bm25 "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/bm25/index.go"
click node_ragcontext "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/llm/rag.go"
click node_config "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/config/loader.go"
click node_watcher "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/watch/watcher.go"
click node_identity "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/identity/identity.go"
click node_dbpool "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/database/pool.go"
click node_dbsearch "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/database/search.go"
click node_llmfactory "https://github.com/pgedge/pgedge-rag-server/blob/main/internal/llm/factory.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_main,node_http,node_routes,node_handlers,node_client toneBlue
class node_manager,node_orchestrator,node_bm25,node_ragcontext toneAmber
class node_dbpool,node_dbsearch toneMint
class node_pg,node_llmfactory,node_llmproviders toneRose
class node_config,node_watcher,node_identity toneIndigo
```

## Components

### Service runtime

- [Server startup](https://github.com/pgedge/pgedge-rag-server/blob/main/cmd/pgedge-rag-server/main.go): `cmd/pgedge-rag-server/main.go`
- [HTTP server](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/server.go): `internal/server/server.go`
- [API routes](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/routes.go): `internal/server/routes.go`
- [Request handlers](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/server/handlers.go): `internal/server/handlers.go`

### RAG query path

- [Pipeline manager](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/manager.go): `internal/pipeline/manager.go`
- [RAG orchestrator](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/pipeline/orchestrator.go): `internal/pipeline/orchestrator.go`
- [BM25 index](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/bm25/index.go): `internal/bm25/index.go`
- [Prompt context](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/llm/rag.go): `internal/llm/rag.go`

### Corpus access

- [Database pool](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/database/pool.go): `internal/database/pool.go`
- [Corpus search](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/database/search.go): `internal/database/search.go`

### External systems

- **PostgreSQL + pgvector**
- [Provider factory](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/llm/factory.go): `internal/llm/factory.go`
- **Embedding and LLM providers**

### Configuration and identity

- [Config loader](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/config/loader.go): `internal/config/loader.go`
- [Config watcher](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/watch/watcher.go): `internal/watch/watcher.go`
- [Caller identity](https://github.com/pgedge/pgedge-rag-server/blob/main/internal/identity/identity.go): `internal/identity/identity.go`

### Other components

- **API client**

## Connections

- API client → HTTP server: sends requests
- Server startup → Config loader: loads config
- Server startup → Pipeline manager: creates pipelines
- Server startup → HTTP server: starts server
- Server startup → Config watcher: watches config
- Config watcher → Config loader: triggers reload
- HTTP server → API routes: registers routes
- API routes → Request handlers: dispatches requests
- Request handlers → Caller identity: extracts identity
- Request handlers → Pipeline manager: selects pipeline
- Request handlers → RAG orchestrator: executes query
- Pipeline manager → Database pool: creates pools
- Pipeline manager → Provider factory: creates clients
- Pipeline manager → RAG orchestrator: configures pipeline
- RAG orchestrator → Corpus search: searches corpus
- RAG orchestrator → Corpus search: fetches BM25 docs
- Corpus search → Database pool: uses pool
- Database pool → PostgreSQL + pgvector: queries
- RAG orchestrator → BM25 index: ranks text
- RAG orchestrator → Prompt context: formats context
- RAG orchestrator → Embedding and LLM providers: embeds and generates
- Provider factory → Embedding and LLM providers: constructs clients
- RAG orchestrator → Embedding and LLM providers: reranks optionally