# d-hackmt/enterprise-rag-with-guardrails-gateways-evals architecture

> Architecture diagram of the GitHub repository d-hackmt/enterprise-rag-with-guardrails-gateways-evals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals
- Repository: https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals

## Overview

Enterprise Agentic RAG accepts user questions through a Streamlit chat interface and FastAPI. The API applies NeMo Guardrails and an optional Redis semantic-cache check before invoking a LangGraph planner, retrieval, and response workflow; answers use Portkey-routed LLMs, with conversation state checkpointed to memory. Separately, GCS uploads trigger document parsing, chunking, embedding, and Qdrant indexing. The evaluation dashboard runs live queries and guardrail checks, scores results, and persists history. Edges reflect the README and shown source references; some cloud wiring and evaluation internals are documented but not sampled.

Main entry points: [`app/agents/graph.py`](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/graph.py) (Agent Graph), [`app/ingestion/processor.py`](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/ingestion/processor.py) (Ingestion Processor), [`evals/app.py`](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/app.py) (Evaluation Dashboard), [`app/main.py`](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/main.py) (Query API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query and Agent"]
  node_chat["Chat UI<br/>[app.py]"]
  node_api["Query API<br/>[main.py]"]
  node_rails["Guardrails<br/>[rails.py]"]
  node_rules["Safety Rules<br/>[colang_rules.py]"]
  node_agent["Agent Graph<br/>[graph.py]"]
  node_state["Agent State<br/>[state.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_retriever["Retriever<br/>[retriever.py]"]
  node_responder["Responder<br/>[responder.py]"]
end

subgraph group_knowledge["Knowledge Ingestion"]
  node_qdrant["Qdrant Search<br/>[qdrant_service.py]"]
  node_vector_db[("Qdrant Vector DB")]
  node_ranker["FlashRank Reranker<br/>[ranking_service.py]"]
  node_gcs_upload(("GCS Upload"))
  node_eventarc["Eventarc Trigger"]
  node_ingestion["Ingestion Processor<br/>[processor.py]"]
  node_loaders["Document Loaders"]
  node_chunker["Text Chunker<br/>[splitter.py]"]
  node_processed_gcs[("Processed Documents")]
end

subgraph group_platform["State and Integrations"]
  node_cache["Semantic Cache"]
  node_redis[("Redis Cache")]
  node_embedding["Embedding Service<br/>[embedding.py]"]
  node_gateway["Portkey Gateway<br/>[client.py]"]
  node_llm["Groq Models"]
  node_checkpoint["Conversation Checkpointer<br/>[graph.py]"]
  node_postgres_service["Postgres Connection"]
  node_postgres[("Cloud SQL Postgres")]
end

subgraph group_evaluation["Evaluation"]
  node_eval_app["Evaluation Dashboard<br/>[app.py]"]
  node_eval_pipeline["Live Query Pipeline<br/>[pipeline.py]"]
  node_guard_eval["Guardrails Evaluation<br/>[guardrails_eval.py]"]
  node_metrics["RAGAS Metrics<br/>[metrics.py]"]
  node_eval_store["Evaluation History<br/>[store.py]"]
  node_history_gcs[("GCS Eval History")]
end

node_user(("User"))
node_eval_user(("Evaluator"))

node_user -->|"asks"| node_chat
node_chat -->|"submits query"| node_api
node_api -->|"checks safety"| node_rails
node_rails -->|"uses rules"| node_rules
node_api -->|"checks and stores"| node_cache
node_cache -->|"reads and writes"| node_redis
node_api -->|"invokes"| node_agent
node_agent -->|"dispatches"| node_planner
node_agent -->|"routes technical"| node_retriever
node_agent -->|"routes conversational"| node_responder
node_agent -->|"uses schema"| node_state
node_retriever -->|"searches"| node_qdrant
node_qdrant -->|"embeds query"| node_embedding
node_qdrant -->|"queries vectors"| node_vector_db
node_retriever -->|"reranks results"| node_ranker
node_retriever -->|"provides context"| node_responder
node_responder -->|"requests generation"| node_gateway
node_gateway -->|"routes with fallback"| node_llm
node_agent -->|"persists conversation"| node_checkpoint
node_checkpoint -->|"uses connection"| node_postgres_service
node_postgres_service -->|"connects to"| node_postgres
node_gcs_upload -->|"emits finalized event"| node_eventarc
node_eventarc -->|"triggers processing"| node_ingestion
node_ingestion -->|"parses files"| node_loaders
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embedding
node_ingestion -->|"stores processed data"| node_processed_gcs
node_ingestion -->|"indexes vectors"| node_vector_db
node_eval_user -->|"runs evaluation"| node_eval_app
node_eval_app -->|"starts live runs"| node_eval_pipeline
node_eval_pipeline -->|"posts queries"| node_api
node_eval_app -->|"runs safety checks"| node_guard_eval
node_eval_app -->|"scores results"| node_metrics
node_eval_app -->|"loads and saves runs"| node_eval_store
node_eval_store -->|"persists history"| node_history_gcs

click node_chat "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/ui/app.py"
click node_api "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/main.py"
click node_rails "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/guardrails/rails.py"
click node_rules "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/guardrails/colang_rules.py"
click node_cache "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/gcp/redis_semantic_cache.py"
click node_agent "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/graph.py"
click node_state "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/state.py"
click node_planner "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/planner.py"
click node_retriever "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/retriever.py"
click node_responder "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/responder.py"
click node_embedding "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/embedding.py"
click node_qdrant "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/qdrant_service.py"
click node_ranker "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/ranking_service.py"
click node_gateway "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/gateway/client.py"
click node_checkpoint "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/graph.py"
click node_postgres_service "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/gcp/database_service.py"
click node_ingestion "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/ingestion/processor.py"
click node_loaders "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/tree/main/app/ingestion/loaders"
click node_chunker "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/ingestion/chunking/splitter.py"
click node_eval_app "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/app.py"
click node_eval_pipeline "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/pipeline.py"
click node_guard_eval "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/guardrails_eval.py"
click node_metrics "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/metrics.py"
click node_eval_store "https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/store.py"

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_chat,node_api,node_rails,node_rules,node_agent,node_state,node_planner,node_retriever,node_responder,node_user toneBlue
class node_qdrant,node_vector_db,node_ranker,node_gcs_upload,node_eventarc,node_ingestion,node_loaders,node_chunker,node_processed_gcs toneAmber
class node_cache,node_redis,node_embedding,node_gateway,node_llm,node_checkpoint,node_postgres_service,node_postgres toneMint
class node_eval_app,node_eval_pipeline,node_guard_eval,node_metrics,node_eval_store,node_history_gcs toneRose
class node_eval_user toneIndigo
```

## Components

### Query and Agent

- [Chat UI](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/ui/app.py): `ui/app.py`
- [Query API](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/main.py): `app/main.py`
- [Guardrails](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/guardrails/rails.py): `app/guardrails/rails.py`
- [Safety Rules](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/guardrails/colang_rules.py): `app/guardrails/colang_rules.py`
- [Agent Graph](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Agent State](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/state.py): `app/agents/state.py`
- [Planner](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/planner.py): `app/agents/nodes/planner.py`
- [Retriever](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/retriever.py): `app/agents/nodes/retriever.py`
- [Responder](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/nodes/responder.py): `app/agents/nodes/responder.py`

### Knowledge Ingestion

- [Qdrant Search](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/qdrant_service.py): `app/services/retrieval/qdrant_service.py`
- **Qdrant Vector DB**
- [FlashRank Reranker](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/ranking_service.py): `app/services/retrieval/ranking_service.py`
- **GCS Upload**
- **Eventarc Trigger**
- [Ingestion Processor](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/ingestion/processor.py): `app/ingestion/processor.py`
- [Document Loaders](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/tree/main/app/ingestion/loaders): `app/ingestion/loaders`
- [Text Chunker](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/ingestion/chunking/splitter.py): `app/ingestion/chunking/splitter.py`
- **Processed Documents**

### State and Integrations

- [Semantic Cache](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/gcp/redis_semantic_cache.py): `app/services/gcp/redis_semantic_cache.py`
- **Redis Cache**
- [Embedding Service](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/retrieval/embedding.py): `app/services/retrieval/embedding.py`
- [Portkey Gateway](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/gateway/client.py): `app/gateway/client.py`
- **Groq Models**
- [Conversation Checkpointer](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Postgres Connection](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/app/services/gcp/database_service.py): `app/services/gcp/database_service.py`
- **Cloud SQL Postgres**

### Evaluation

- [Evaluation Dashboard](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/app.py): `evals/app.py`
- [Live Query Pipeline](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/pipeline.py): `evals/pipeline.py`
- [Guardrails Evaluation](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/guardrails_eval.py): `evals/guardrails_eval.py`
- [RAGAS Metrics](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/metrics.py): `evals/metrics.py`
- [Evaluation History](https://github.com/d-hackmt/enterprise-rag-with-guardrails-gateways-evals/blob/main/evals/store.py): `evals/store.py`
- **GCS Eval History**

### Other components

- **User**
- **Evaluator**

## Connections

- User → Chat UI: asks
- Chat UI → Query API: submits query
- Query API → Guardrails: checks safety (evidence: `app/main.py`)
- Guardrails → Safety Rules: uses rules (evidence: `app/guardrails/rails.py`)
- Query API → Semantic Cache: checks and stores (evidence: `app/main.py`)
- Semantic Cache → Redis Cache: reads and writes
- Query API → Agent Graph: invokes (evidence: `app/main.py`)
- Agent Graph → Planner: dispatches (evidence: `app/agents/graph.py`)
- Agent Graph → Retriever: routes technical (evidence: `app/agents/graph.py`)
- Agent Graph → Responder: routes conversational (evidence: `app/agents/graph.py`)
- Agent Graph → Agent State: uses schema (evidence: `app/agents/graph.py`)
- Retriever → Qdrant Search: searches (evidence: `app/agents/nodes/retriever.py`)
- Qdrant Search → Embedding Service: embeds query (evidence: `app/services/retrieval/qdrant_service.py`)
- Qdrant Search → Qdrant Vector DB: queries vectors
- Retriever → FlashRank Reranker: reranks results (evidence: `app/agents/nodes/retriever.py`)
- Retriever → Responder: provides context (evidence: `app/agents/graph.py`)
- Responder → Portkey Gateway: requests generation
- Portkey Gateway → Groq Models: routes with fallback (evidence: `app/gateway/client.py`)
- Agent Graph → Conversation Checkpointer: persists conversation (evidence: `app/agents/graph.py`)
- Conversation Checkpointer → Postgres Connection: uses connection (evidence: `app/agents/graph.py`)
- Postgres Connection → Cloud SQL Postgres: connects to
- GCS Upload → Eventarc Trigger: emits finalized event
- Eventarc Trigger → Ingestion Processor: triggers processing
- Ingestion Processor → Document Loaders: parses files (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Text Chunker: chunks text (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Embedding Service: embeds chunks (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Processed Documents: stores processed data (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Qdrant Vector DB: indexes vectors (evidence: `app/ingestion/processor.py`)
- Evaluator → Evaluation Dashboard: runs evaluation
- Evaluation Dashboard → Live Query Pipeline: starts live runs (evidence: `evals/app.py`)
- Live Query Pipeline → Query API: posts queries (evidence: `evals/pipeline.py`)
- Evaluation Dashboard → Guardrails Evaluation: runs safety checks (evidence: `evals/app.py`)
- Evaluation Dashboard → RAGAS Metrics: scores results (evidence: `evals/app.py`)
- Evaluation Dashboard → Evaluation History: loads and saves runs (evidence: `evals/app.py`)
- Evaluation History → GCS Eval History: persists history
