# eklakh-ai-engineer/enterprise-rag architecture

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

- Interactive diagram: https://gitdiagram.com/eklakh-ai-engineer/enterprise-rag
- Repository: https://github.com/eklakh-ai-engineer/enterprise-rag

## Overview

Enterprise RAG is an evidence-grounded document search and question-answering product, with a React workspace and FastAPI backend. Users authenticate, upload PDFs for asynchronous ingestion and indexing, then query the indexed evidence; answers carry mapped citations and undergo faithfulness and quality checks. The graph separates document preparation, retrieval and answer validation, plus persistence and external services. README documents capabilities beyond the sampled code; those links are cited there, while unsampled implementation details are not inferred.

Main entry points: [`app/query/pipeline.py`](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/query/pipeline.py) (Query orchestration), [`app/api/main.py`](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/api/main.py) (FastAPI routes), [`app/ingestion/worker.py`](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/ingestion/worker.py) (Ingestion worker), [`frontend/src/App.jsx`](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/App.jsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and API"]
  node_ui["Workspace UI<br/>[App.jsx]"]
  node_authclient["Auth client<br/>[auth.js]"]
  node_ragclient["RAG client<br/>[rag.js]"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_auth["Token authentication<br/>[service.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_pdf["PDF parsing<br/>[pdf_parser.py]"]
  node_chunk["Evidence chunking"]
  node_ingestpipe["Ingestion pipeline<br/>[pipeline.py]"]
  node_worker["Ingestion worker<br/>[worker.py]"]
  node_indexpipe["Document indexing<br/>[pipeline.py]"]
  node_embed["Embedding provider<br/>[embeddings.py]"]
end

subgraph group_search["Retrieval and answers"]
  node_querypipe["Query orchestration<br/>[pipeline.py]"]
  node_dense["Dense retrieval<br/>[retriever.py]"]
  node_bm25["BM25 retrieval<br/>[retriever.py]"]
  node_hybrid["Hybrid fusion<br/>[retriever.py]"]
  node_rerank["Cross-encoder reranking<br/>[cross_encoder.py]"]
  node_context["Context assembly<br/>[context.py]"]
  node_generator["Grounded generation<br/>[rag_generator.py]"]
  node_provider["OpenRouter client<br/>[openrouter.py]"]
end

subgraph group_quality["Evidence and evaluation"]
  node_citations["Citation mapping<br/>[mapper.py]"]
  node_citationcheck["Citation validation<br/>[verifier.py]"]
  node_faithfulness["Faithfulness check<br/>[checker.py]"]
  node_evaluation["Answer evaluation"]
  node_metrics["Pipeline metrics<br/>[metrics.py]"]
end

subgraph group_state["Persistence and integrations"]
  node_entities["Domain records<br/>[entities.py]"]
  node_repositories["Repositories<br/>[repositories.py]"]
  node_supabase[("Supabase persistence<br/>[supabase.py]")]
  node_storage[("Supabase file storage<br/>[supabase.py]")]
end

node_user(("User"))
node_supabaseauth["Supabase Auth"]
node_openrouter["OpenRouter service"]

node_user -->|"uses"| node_ui
node_ui -->|"signs in"| node_authclient
node_ui -->|"uploads"| node_ragclient
node_ragclient -.->|"requests"| node_api
node_api -->|"authenticates"| node_auth
node_auth -->|"verifies token"| node_supabaseauth
node_api -->|"runs query"| node_querypipe
node_api -->|"stores upload"| node_storage
node_api -->|"creates records"| node_supabase
node_worker -->|"processes document"| node_ingestpipe
node_ingestpipe -->|"parses PDF"| node_pdf
node_ingestpipe -->|"chunks pages"| node_chunk
node_worker -->|"indexes chunks"| node_indexpipe
node_indexpipe -->|"encodes chunks"| node_embed
node_indexpipe -.->|"persists vectors"| node_supabase
node_worker -->|"updates jobs"| node_repositories
node_repositories -->|"uses records"| node_entities
node_querypipe -->|"retrieves candidates"| node_dense
node_querypipe -->|"retrieves candidates"| node_bm25
node_dense -->|"provides candidates"| node_hybrid
node_bm25 -->|"provides candidates"| node_hybrid
node_querypipe -->|"fuses candidates"| node_hybrid
node_querypipe -->|"reranks results"| node_rerank
node_querypipe -->|"assembles context"| node_context
node_querypipe -->|"generates answer"| node_generator
node_generator -->|"requests completion"| node_provider
node_provider -->|"calls model"| node_openrouter
node_querypipe -->|"maps citations"| node_citations
node_querypipe -->|"validates citations"| node_citationcheck
node_querypipe -->|"checks claims"| node_faithfulness
node_querypipe -->|"evaluates answer"| node_evaluation
node_querypipe -->|"records metrics"| node_metrics

click node_ui "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/App.jsx"
click node_authclient "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/api/auth.js"
click node_ragclient "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/api/rag.js"
click node_api "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/api/main.py"
click node_auth "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/auth/service.py"
click node_pdf "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/parsing/pdf_parser.py"
click node_chunk "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/chunking/recursive_chunker.py"
click node_ingestpipe "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/ingestion/pipeline.py"
click node_worker "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/ingestion/worker.py"
click node_indexpipe "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/indexing/pipeline.py"
click node_embed "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/indexing/embeddings.py"
click node_querypipe "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/query/pipeline.py"
click node_dense "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/dense/retriever.py"
click node_bm25 "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/bm25/retriever.py"
click node_hybrid "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/hybrid/retriever.py"
click node_rerank "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/reranking/cross_encoder.py"
click node_context "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/query/context.py"
click node_generator "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/generation/rag_generator.py"
click node_provider "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/generation/openrouter.py"
click node_citations "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/citations/mapper.py"
click node_citationcheck "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/citations/verifier.py"
click node_faithfulness "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/faithfulness/checker.py"
click node_evaluation "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/evaluation/answer_evaluator.py"
click node_metrics "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/observability/metrics.py"
click node_entities "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/entities.py"
click node_repositories "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/repositories.py"
click node_supabase "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/supabase.py"
click node_storage "https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/storage/supabase.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_ui,node_authclient,node_ragclient,node_api,node_auth,node_user toneBlue
class node_pdf,node_chunk,node_ingestpipe,node_worker,node_indexpipe,node_embed toneAmber
class node_querypipe,node_dense,node_bm25,node_hybrid,node_rerank,node_context,node_generator,node_provider,node_openrouter toneMint
class node_citations,node_citationcheck,node_faithfulness,node_evaluation,node_metrics toneRose
class node_entities,node_repositories,node_supabase,node_storage,node_supabaseauth toneIndigo
```

## Components

### Workspace and API

- [Workspace UI](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth client](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/api/auth.js): `frontend/src/api/auth.js`
- [RAG client](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/frontend/src/api/rag.js): `frontend/src/api/rag.js`
- [FastAPI routes](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/api/main.py): `app/api/main.py`
- [Token authentication](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/auth/service.py): `app/auth/service.py`

### Document ingestion

- [PDF parsing](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/parsing/pdf_parser.py): `app/parsing/pdf_parser.py`
- [Evidence chunking](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/chunking/recursive_chunker.py): `app/chunking/recursive_chunker.py`
- [Ingestion pipeline](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [Ingestion worker](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/ingestion/worker.py): `app/ingestion/worker.py`
- [Document indexing](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/indexing/pipeline.py): `app/indexing/pipeline.py`
- [Embedding provider](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/indexing/embeddings.py): `app/indexing/embeddings.py`

### Retrieval and answers

- [Query orchestration](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/query/pipeline.py): `app/query/pipeline.py`
- [Dense retrieval](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/dense/retriever.py): `app/retrieval/dense/retriever.py`
- [BM25 retrieval](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/bm25/retriever.py): `app/retrieval/bm25/retriever.py`
- [Hybrid fusion](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/retrieval/hybrid/retriever.py): `app/retrieval/hybrid/retriever.py`
- [Cross-encoder reranking](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/reranking/cross_encoder.py): `app/reranking/cross_encoder.py`
- [Context assembly](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/query/context.py): `app/query/context.py`
- [Grounded generation](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/generation/rag_generator.py): `app/generation/rag_generator.py`
- [OpenRouter client](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/generation/openrouter.py): `app/generation/openrouter.py`

### Evidence and evaluation

- [Citation mapping](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/citations/mapper.py): `app/citations/mapper.py`
- [Citation validation](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/citations/verifier.py): `app/citations/verifier.py`
- [Faithfulness check](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/faithfulness/checker.py): `app/faithfulness/checker.py`
- [Answer evaluation](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/evaluation/answer_evaluator.py): `app/evaluation/answer_evaluator.py`
- [Pipeline metrics](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/observability/metrics.py): `app/observability/metrics.py`

### Persistence and integrations

- [Domain records](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/entities.py): `app/persistence/entities.py`
- [Repositories](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/repositories.py): `app/persistence/repositories.py`
- [Supabase persistence](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/persistence/supabase.py): `app/persistence/supabase.py`
- [Supabase file storage](https://github.com/eklakh-ai-engineer/enterprise-rag/blob/main/app/storage/supabase.py): `app/storage/supabase.py`

### Other components

- **User**
- **Supabase Auth**
- **OpenRouter service**

## Connections

- User → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → Auth client: signs in (evidence: `frontend/src/App.jsx`)
- Workspace UI → RAG client: uploads (evidence: `frontend/src/App.jsx`)
- RAG client → FastAPI routes: requests
- FastAPI routes → Token authentication: authenticates (evidence: `app/api/main.py`)
- Token authentication → Supabase Auth: verifies token (evidence: `app/auth/service.py`)
- FastAPI routes → Query orchestration: runs query (evidence: `app/api/main.py`)
- FastAPI routes → Supabase file storage: stores upload (evidence: `app/api/main.py`)
- FastAPI routes → Supabase persistence: creates records (evidence: `app/api/main.py`)
- Ingestion worker → Ingestion pipeline: processes document (evidence: `app/ingestion/worker.py`)
- Ingestion pipeline → PDF parsing: parses PDF (evidence: `app/ingestion/pipeline.py`)
- Ingestion pipeline → Evidence chunking: chunks pages (evidence: `app/ingestion/pipeline.py`)
- Ingestion worker → Document indexing: indexes chunks (evidence: `app/ingestion/worker.py`)
- Document indexing → Embedding provider: encodes chunks (evidence: `app/indexing/pipeline.py`)
- Document indexing → Supabase persistence: persists vectors
- Ingestion worker → Repositories: updates jobs (evidence: `app/ingestion/worker.py`)
- Repositories → Domain records: uses records (evidence: `app/persistence/repositories.py`)
- Query orchestration → Dense retrieval: retrieves candidates (evidence: `app/query/pipeline.py`)
- Query orchestration → BM25 retrieval: retrieves candidates (evidence: `app/query/pipeline.py`)
- Dense retrieval → Hybrid fusion: provides candidates (evidence: `app/retrieval/hybrid/retriever.py`)
- BM25 retrieval → Hybrid fusion: provides candidates (evidence: `app/retrieval/hybrid/retriever.py`)
- Query orchestration → Hybrid fusion: fuses candidates (evidence: `app/query/pipeline.py`)
- Query orchestration → Cross-encoder reranking: reranks results (evidence: `app/query/pipeline.py`)
- Query orchestration → Context assembly: assembles context (evidence: `README.md`)
- Query orchestration → Grounded generation: generates answer (evidence: `app/query/pipeline.py`)
- Grounded generation → OpenRouter client: requests completion (evidence: `app/generation/rag_generator.py`)
- OpenRouter client → OpenRouter service: calls model (evidence: `app/generation/openrouter.py`)
- Query orchestration → Citation mapping: maps citations (evidence: `app/query/pipeline.py`)
- Query orchestration → Citation validation: validates citations (evidence: `README.md`)
- Query orchestration → Faithfulness check: checks claims (evidence: `app/query/pipeline.py`)
- Query orchestration → Answer evaluation: evaluates answer (evidence: `app/query/pipeline.py`)
- Query orchestration → Pipeline metrics: records metrics (evidence: `app/query/pipeline.py`)
