# ahmedrabea0302/go-rag-based-chat-app architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedrabea0302/go-rag-based-chat-app
- Repository: https://github.com/ahmedrabea0302/go-rag-based-chat-app

## Overview

This Go application ingests Markdown and text files into a pgvector-backed retrieval index, then uses retrieved context to support LLM chat through a terminal REPL. The runtime also exposes a web route that renders a chat page; the sampled server code does not show a web chat submission or response workflow. The graph separates ingestion, retrieval, chat, and storage. Some capabilities are represented only by their exact paths because their implementation was not sampled.

Main entry points: [`app/app.go`](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/app/app.go) (Application runtime), [`rag/retriever.go`](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/retriever.go) (Retriever), [`ingest/ingest.go`](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/ingest.go) (Content ingestion), [`chat/repl.go`](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/chat/repl.go) (Terminal chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_main["CLI entry<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_app["Application runtime<br/>[app.go]"]
end

subgraph group_ingestion["Document ingestion"]
  node_source_docs["Source documents"]
  node_watcher["Directory watcher<br/>[watcher.go]"]
  node_processor["Content ingestion<br/>[ingest.go]"]
  node_chunker["Text chunker<br/>[chunk.go]"]
end

subgraph group_retrieval["Retrieval and prompts"]
  node_embedder["Embedding client<br/>[embed.go]"]
  node_retriever["Retriever<br/>[retriever.go]"]
  node_rewriter["Query rewriter<br/>[rewriter.go]"]
  node_prompt["Prompt formatting<br/>[prompt.go]"]
end

subgraph group_chat["Chat interfaces"]
  node_repl["Terminal chat<br/>[repl.go]"]
  node_web["Web server<br/>[server.go]"]
  node_template["Chat page template<br/>[chat.gohtml]"]
  node_chat_client["Chat client<br/>[client.go]"]
end

subgraph group_storage["Vector storage"]
  node_store_contract["Vector store contract<br/>[store.go]"]
  node_pgvector["Pgvector adapter<br/>[pgvector.go]"]
end

node_user(("User"))
node_model_service{{"LLM service"}}
node_database[("PostgreSQL")]

node_user -->|"starts"| node_main
node_main -->|"loads"| node_config
node_main -->|"runs"| node_app
node_app -->|"uses settings"| node_config
node_app -->|"creates"| node_embedder
node_app -->|"creates"| node_chat_client
node_app -->|"opens store"| node_pgvector
node_app -->|"starts"| node_watcher
node_app -->|"creates"| node_retriever
node_app -->|"creates"| node_rewriter
node_app -->|"starts"| node_repl
node_app -->|"starts"| node_web
node_user -->|"enters prompts"| node_repl
node_user -->|"opens chat page"| node_web
node_watcher -->|"watches"| node_source_docs
node_watcher -->|"processes files"| node_processor
node_processor -->|"chunks text"| node_chunker
node_processor -->|"embeds chunks"| node_embedder
node_processor -->|"deletes and upserts"| node_store_contract
node_repl -->|"retrieves context"| node_retriever
node_repl -->|"requests reply"| node_chat_client
node_retriever -->|"rewrites query"| node_rewriter
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"queries vectors"| node_store_contract
node_web -->|"renders page"| node_template
node_chat_client -->|"streams completion"| node_model_service
node_pgvector -->|"queries and writes"| node_database

click node_main "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/cmd/rag/main.go"
click node_config "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/config/config.go"
click node_app "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/app/app.go"
click node_watcher "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/watcher.go"
click node_processor "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/ingest.go"
click node_chunker "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/chunk.go"
click node_embedder "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/llm/embed.go"
click node_retriever "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/retriever.go"
click node_rewriter "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/rewriter.go"
click node_prompt "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/prompt.go"
click node_repl "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/chat/repl.go"
click node_web "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/web/server.go"
click node_template "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/web/templates/chat.gohtml"
click node_chat_client "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/llm/client.go"
click node_store_contract "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/vector/store.go"
click node_pgvector "https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/vector/pgvector/pgvector.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_config,node_app,node_user toneBlue
class node_source_docs,node_watcher,node_processor,node_chunker,node_database toneAmber
class node_embedder,node_retriever,node_rewriter,node_prompt toneMint
class node_repl,node_web,node_template,node_chat_client toneRose
class node_store_contract,node_pgvector,node_model_service toneIndigo
```

## Components

### Runtime and configuration

- [CLI entry](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/cmd/rag/main.go): `cmd/rag/main.go`
- [Configuration](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/config/config.go): `config/config.go`
- [Application runtime](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/app/app.go): `app/app.go`

### Document ingestion

- **Source documents**
- [Directory watcher](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/watcher.go): `ingest/watcher.go`
- [Content ingestion](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/ingest.go): `ingest/ingest.go`
- [Text chunker](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/ingest/chunk.go): `ingest/chunk.go`

### Retrieval and prompts

- [Embedding client](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/llm/embed.go): `llm/embed.go`
- [Retriever](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/retriever.go): `rag/retriever.go`
- [Query rewriter](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/rewriter.go): `rag/rewriter.go`
- [Prompt formatting](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/rag/prompt.go): `rag/prompt.go`

### Chat interfaces

- [Terminal chat](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/chat/repl.go): `chat/repl.go`
- [Web server](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/web/server.go): `web/server.go`
- [Chat page template](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/web/templates/chat.gohtml): `web/templates/chat.gohtml`
- [Chat client](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/llm/client.go): `llm/client.go`

### Vector storage

- [Vector store contract](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/vector/store.go): `vector/store.go`
- [Pgvector adapter](https://github.com/ahmedrabea0302/go-rag-based-chat-app/blob/main/vector/pgvector/pgvector.go): `vector/pgvector/pgvector.go`

### Other components

- **User**
- **LLM service**
- **PostgreSQL**

## Connections

- User → CLI entry: starts (evidence: `cmd/rag/main.go`)
- CLI entry → Configuration: loads (evidence: `cmd/rag/main.go`)
- CLI entry → Application runtime: runs (evidence: `cmd/rag/main.go`)
- Application runtime → Configuration: uses settings (evidence: `app/app.go`)
- Application runtime → Embedding client: creates (evidence: `app/app.go`)
- Application runtime → Chat client: creates (evidence: `app/app.go`)
- Application runtime → Pgvector adapter: opens store (evidence: `app/app.go`)
- Application runtime → Directory watcher: starts (evidence: `app/app.go`)
- Application runtime → Retriever: creates (evidence: `app/app.go`)
- Application runtime → Query rewriter: creates (evidence: `app/app.go`)
- Application runtime → Terminal chat: starts (evidence: `app/app.go`)
- Application runtime → Web server: starts (evidence: `app/app.go`)
- User → Terminal chat: enters prompts (evidence: `chat/repl.go`)
- User → Web server: opens chat page (evidence: `web/server.go`)
- Directory watcher → Source documents: watches (evidence: `ingest/watcher.go`)
- Directory watcher → Content ingestion: processes files (evidence: `ingest/watcher.go`)
- Content ingestion → Text chunker: chunks text (evidence: `ingest/ingest.go`)
- Content ingestion → Embedding client: embeds chunks (evidence: `ingest/ingest.go`)
- Content ingestion → Vector store contract: deletes and upserts (evidence: `ingest/ingest.go`)
- Terminal chat → Retriever: retrieves context (evidence: `chat/repl.go`)
- Terminal chat → Chat client: requests reply (evidence: `chat/repl.go`)
- Retriever → Query rewriter: rewrites query (evidence: `rag/retriever.go`)
- Retriever → Embedding client: embeds query (evidence: `rag/retriever.go`)
- Retriever → Vector store contract: queries vectors (evidence: `rag/retriever.go`)
- Web server → Chat page template: renders page (evidence: `web/server.go`)
- Chat client → LLM service: streams completion (evidence: `llm/client.go`)
- Pgvector adapter → PostgreSQL: queries and writes (evidence: `vector/pgvector/pgvector.go`)