# nguyen756/rag architecture

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

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

## Overview

This is a containerized RAG service for game-mechanics questions: a Handlebars web UI forwards queries to a FastAPI backend, which checks a semantic answer cache before routing uncached questions to Gemini tools or FAISS retrieval. The backend also ingests PDF or scraped text, cleans and chunks it, deduplicates chunks, and persists embeddings and metadata. The README documents Nginx, Terraform, and Prometheus/Grafana operations. Those infrastructure and monitoring links are shown where documented; unsampled implementation details are not inferred.

Main entry points: [`app/main.py`](https://github.com/nguyen756/rag/blob/main/app/main.py) (Query API and cache), [`app/scraper.py`](https://github.com/nguyen756/rag/blob/main/app/scraper.py) (PDF and web extraction), [`app/vector_engine.py`](https://github.com/nguyen756/rag/blob/main/app/vector_engine.py) (Vector search), [`routes/answer.route.js`](https://github.com/nguyen756/rag/blob/main/routes/answer.route.js) (Answer route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_ui["Question form<br/>[index.handlebars]"]
  node_web_route["Answer route<br/>[answer.route.js]"]
  node_web_server["Express server<br/>[server.js]"]
end

subgraph group_backend["Query and tools"]
  node_api["Query API and cache<br/>[main.py]"]
  node_tool_functions["Agent calculations<br/>[agent.py]"]
end

subgraph group_ingestion["Ingestion and storage"]
  node_vector_search["Vector search<br/>[vector_engine.py]"]
  node_scraper["PDF and web extraction<br/>[scraper.py]"]
  node_source_data["PDF source<br/>[Hard Hit-3.pdf]"]
  node_text_utils["Cleaning and chunking<br/>[utils.py]"]
  node_dedupe[("Hash ledger<br/>[sync.py]")]
  node_vector_store[("Vector index and metadata")]
end

subgraph group_operations["Operations"]
  node_nginx["HTTPS proxy<br/>[nginx.conf]"]
  node_terraform["AWS provisioning<br/>[main.tf]"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
end

node_user(("Questioner"))
node_gemini{{"Gemini API"}}
node_web_source{{"Scraped web pages"}}
node_grafana["Grafana dashboards"]

node_user -->|"enters question"| node_ui
node_ui -->|"submits form"| node_web_route
node_web_server -->|"mounts route"| node_web_route
node_web_route -->|"posts query"| node_api
node_api -->|"returns answer"| node_web_route
node_api -->|"requests tool choice"| node_gemini
node_api -->|"calls calculation"| node_tool_functions
node_api -->|"searches retrieved query"| node_vector_search
node_vector_search -->|"loads and searches"| node_vector_store
node_api -->|"reads configured PDF"| node_source_data
node_api -->|"extracts PDF text"| node_scraper
node_scraper -->|"cleans and chunks"| node_text_utils
node_scraper -->|"checks chunk IDs"| node_dedupe
node_api -->|"embeds extracted chunks"| node_vector_search
node_vector_search -->|"saves index and metadata"| node_vector_store
node_scraper -.->|"fetches pages"| node_web_source
node_user -.->|"initiates HTTPS request"| node_nginx
node_nginx -.->|"proxies traffic"| node_web_server
node_terraform -.->|"provisions cloud gateway"| node_nginx
node_api -->|"exposes metrics for scraping"| node_prometheus
node_prometheus -->|"visualizes metrics"| node_grafana

click node_ui "https://github.com/nguyen756/rag/blob/main/views/index.handlebars"
click node_web_route "https://github.com/nguyen756/rag/blob/main/routes/answer.route.js"
click node_web_server "https://github.com/nguyen756/rag/blob/main/server.js"
click node_api "https://github.com/nguyen756/rag/blob/main/app/main.py"
click node_tool_functions "https://github.com/nguyen756/rag/blob/main/app/agent/agent.py"
click node_vector_search "https://github.com/nguyen756/rag/blob/main/app/vector_engine.py"
click node_scraper "https://github.com/nguyen756/rag/blob/main/app/scraper.py"
click node_source_data "https://github.com/nguyen756/rag/blob/main/data/Hard%20Hit-3.pdf"
click node_text_utils "https://github.com/nguyen756/rag/blob/main/app/utils.py"
click node_dedupe "https://github.com/nguyen756/rag/blob/main/app/sync.py"
click node_vector_store "https://github.com/nguyen756/rag/blob/main/data/vector_database.index"
click node_nginx "https://github.com/nguyen756/rag/blob/main/nginx/nginx.conf"
click node_terraform "https://github.com/nguyen756/rag/blob/main/infrastructure/main.tf"
click node_prometheus "https://github.com/nguyen756/rag/blob/main/prometheus.yml"

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_ui,node_web_route,node_web_server toneBlue
class node_api,node_tool_functions toneAmber
class node_vector_search,node_scraper,node_source_data,node_text_utils,node_dedupe,node_vector_store,node_gemini toneMint
class node_nginx,node_terraform,node_prometheus toneRose
class node_user,node_web_source,node_grafana toneIndigo
```

## Components

### Web interface

- [Question form](https://github.com/nguyen756/rag/blob/main/views/index.handlebars): `views/index.handlebars`
- [Answer route](https://github.com/nguyen756/rag/blob/main/routes/answer.route.js): `routes/answer.route.js`
- [Express server](https://github.com/nguyen756/rag/blob/main/server.js): `server.js`

### Query and tools

- [Query API and cache](https://github.com/nguyen756/rag/blob/main/app/main.py): `app/main.py`
- [Agent calculations](https://github.com/nguyen756/rag/blob/main/app/agent/agent.py): `app/agent/agent.py`

### Ingestion and storage

- [Vector search](https://github.com/nguyen756/rag/blob/main/app/vector_engine.py): `app/vector_engine.py`
- [PDF and web extraction](https://github.com/nguyen756/rag/blob/main/app/scraper.py): `app/scraper.py`
- [PDF source](https://github.com/nguyen756/rag/blob/main/data/Hard%20Hit-3.pdf): `data/Hard Hit-3.pdf`
- [Cleaning and chunking](https://github.com/nguyen756/rag/blob/main/app/utils.py): `app/utils.py`
- [Hash ledger](https://github.com/nguyen756/rag/blob/main/app/sync.py): `app/sync.py`
- [Vector index and metadata](https://github.com/nguyen756/rag/blob/main/data/vector_database.index): `data/vector_database.index`

### Operations

- [HTTPS proxy](https://github.com/nguyen756/rag/blob/main/nginx/nginx.conf): `nginx/nginx.conf`
- [AWS provisioning](https://github.com/nguyen756/rag/blob/main/infrastructure/main.tf): `infrastructure/main.tf`
- [Prometheus](https://github.com/nguyen756/rag/blob/main/prometheus.yml): `prometheus.yml`

### Other components

- **Questioner**
- **Gemini API**
- **Scraped web pages**
- **Grafana dashboards**

## Connections

- Questioner → Question form: enters question
- Question form → Answer route: submits form (evidence: `routes/answer.route.js`)
- Express server → Answer route: mounts route (evidence: `server.js`)
- Answer route → Query API and cache: posts query (evidence: `routes/answer.route.js`)
- Query API and cache → Answer route: returns answer (evidence: `routes/answer.route.js`)
- Query API and cache → Gemini API: requests tool choice (evidence: `app/main.py`)
- Query API and cache → Agent calculations: calls calculation (evidence: `app/main.py`)
- Query API and cache → Vector search: searches retrieved query (evidence: `app/main.py`)
- Vector search → Vector index and metadata: loads and searches (evidence: `app/vector_engine.py`)
- Query API and cache → PDF source: reads configured PDF (evidence: `app/main.py`)
- Query API and cache → PDF and web extraction: extracts PDF text (evidence: `app/main.py`)
- PDF and web extraction → Cleaning and chunking: cleans and chunks (evidence: `app/scraper.py`)
- PDF and web extraction → Hash ledger: checks chunk IDs (evidence: `app/scraper.py`)
- Query API and cache → Vector search: embeds extracted chunks (evidence: `app/main.py`)
- Vector search → Vector index and metadata: saves index and metadata (evidence: `app/vector_engine.py`)
- PDF and web extraction → Scraped web pages: fetches pages (evidence: `app/scraper.py`)
- Questioner → HTTPS proxy: initiates HTTPS request (evidence: `README.md`)
- HTTPS proxy → Express server: proxies traffic (evidence: `README.md`)
- AWS provisioning → HTTPS proxy: provisions cloud gateway (evidence: `README.md`)
- Query API and cache → Prometheus: exposes metrics for scraping (evidence: `README.md`)
- Prometheus → Grafana dashboards: visualizes metrics (evidence: `README.md`)