# akg-git/rbac-based-rag-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/akg-git/rbac-based-rag-assistant
- Repository: https://github.com/akg-git/rbac-based-rag-assistant

## Overview

DocuFi is an internal, role-based RAG assistant with document ingestion, SQL and document-grounded chat, user/role administration, and audit monitoring. A user authenticates, submits a question, and the chat route classifies it for SQL or RAG (with SQL-to-RAG fallback) before returning an answer. Administrators can upload documents and manage users; documents are stored and indexed for retrieval. The repository also includes a substantial evaluation suite for answer quality, retrieval, security, latency, vector DB, SQL, and audit behavior. Several evaluation links rely on the source index because those implementation excerpts were not supplied.

Main entry points: [`app/rag_evaluator/evaluation_pipelines.py`](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/evaluation_pipelines.py) (Evaluation pipeline), [`app/main.py`](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/main.py) (API application), [`app/DocuFi-Frontend/landing_page.py`](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/landing_page.py) (Frontend pages), [`app/routes/document_routes.py`](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/document_routes.py) (Document management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_frontend_ui["Frontend pages<br/>[landing_page.py]"]
  node_frontend_login["Login UI<br/>[login_handler.py]"]
  node_frontend_roles["Role definitions<br/>[roles.py]"]
end

subgraph group_application["Assistant application"]
  node_app_entry["API application<br/>[main.py]"]
  node_user_routes["User administration<br/>[user_routes.py]"]
  node_document_routes["Document management<br/>[document_routes.py]"]
  node_chat_routes["Chat routing<br/>[chat_routes.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_hashing["Password hashing<br/>[hashing.py]"]
  node_audit_context["Request audit context<br/>[audit_context.py]"]
  node_classifier["Query classifier"]
  node_sql_handler["Natural-language SQL<br/>[sql_query.py]"]
  node_rag_handler["RAG response handler<br/>[rag_chain.py]"]
  node_rag_indexing["Document indexing<br/>[rag_module.py]"]
  node_rag_cache["RAG response cache<br/>[response_cache.py]"]
end

subgraph group_data["Data and audit"]
  node_sqlite[("User and document store<br/>[sqlitedb.py]")]
  node_duckdb[("Structured data store<br/>[duckdb.py]")]
  node_audit_log[("Audit event log<br/>[audit_events.py]")]
end

subgraph group_evaluation["Evaluation suite"]
  node_pipeline["Evaluation pipeline"]
  node_dataset["Evaluation datasets"]
  node_answer_eval["Answer quality<br/>[evaluator.py]"]
  node_retrieval_eval["Retrieval quality<br/>[evaluator.py]"]
  node_security_eval["RBAC security<br/>[evaluator.py]"]
  node_latency_eval["Latency<br/>[evaluator.py]"]
  node_vector_eval["Vector DB<br/>[evaluator.py]"]
  node_sql_eval["Text-to-SQL<br/>[evaluator.py]"]
  node_audit_eval["Audit monitoring<br/>[evaluator.py]"]
  node_reports["Evaluation reports"]
end

node_user(("Internal user"))

node_user -.->|"uses"| node_frontend_ui
node_frontend_ui -->|"uses"| node_frontend_login
node_frontend_ui -->|"uses"| node_frontend_roles
node_frontend_ui -.->|"calls API"| node_app_entry
node_app_entry -->|"registers"| node_chat_routes
node_app_entry -->|"registers"| node_document_routes
node_app_entry -->|"registers"| node_user_routes
node_user_routes -->|"authenticates"| node_auth
node_user_routes -->|"reads/writes"| node_sqlite
node_auth -->|"reads credentials"| node_sqlite
node_auth -->|"verifies password"| node_hashing
node_app_entry -->|"initializes"| node_audit_context
node_audit_context -->|"authenticates"| node_auth
node_audit_context -->|"emits events"| node_audit_log
node_document_routes -->|"stores metadata"| node_sqlite
node_document_routes -->|"stores table metadata"| node_duckdb
node_document_routes -->|"indexes documents"| node_rag_indexing
node_chat_routes -->|"classifies query"| node_classifier
node_chat_routes -->|"routes SQL"| node_sql_handler
node_chat_routes -->|"routes RAG/fallback"| node_rag_handler
node_sql_handler -->|"queries schema"| node_duckdb
node_sql_handler -->|"uses cache"| node_rag_cache
node_sql_handler -->|"emits events"| node_audit_log
node_rag_handler -->|"invokes RAG chain"| node_rag_indexing
node_rag_handler -->|"uses cache"| node_rag_cache
node_rag_handler -->|"emits events"| node_audit_log
node_rag_indexing -->|"reads document metadata"| node_sqlite
node_pipeline -->|"builds datasets"| node_dataset
node_pipeline -->|"runs evaluation"| node_answer_eval
node_pipeline -->|"runs evaluation"| node_retrieval_eval
node_pipeline -->|"runs evaluation"| node_security_eval
node_pipeline -->|"runs evaluation"| node_latency_eval
node_pipeline -->|"runs evaluation"| node_vector_eval
node_pipeline -->|"runs evaluation"| node_sql_eval
node_pipeline -->|"runs evaluation"| node_audit_eval
node_pipeline -->|"generates reports"| node_reports

click node_frontend_ui "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/landing_page.py"
click node_frontend_login "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/login_handler.py"
click node_frontend_roles "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/roles.py"
click node_app_entry "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/main.py"
click node_user_routes "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/user_routes.py"
click node_document_routes "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/document_routes.py"
click node_chat_routes "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/chat_routes.py"
click node_auth "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/authentication/auth.py"
click node_hashing "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/authentication/hashing.py"
click node_audit_context "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/audit_context.py"
click node_classifier "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/query_classifier.py"
click node_sql_handler "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/sql_query.py"
click node_rag_handler "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/rag_chain.py"
click node_rag_indexing "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/rag_module.py"
click node_rag_cache "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/response_cache.py"
click node_sqlite "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/schemas/sqlitedb.py"
click node_duckdb "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/schemas/duckdb.py"
click node_audit_log "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/audit_events.py"
click node_pipeline "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/evaluation_pipelines.py"
click node_dataset "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/evaluation_dataset_builder.py"
click node_answer_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/answer_quality/evaluator.py"
click node_retrieval_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/retrieval/evaluator.py"
click node_security_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/rbac_security/evaluator.py"
click node_latency_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/latency/evaluator.py"
click node_vector_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/vector_db/evaluator.py"
click node_sql_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/text_to_sql/evaluator.py"
click node_audit_eval "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/audit_monitoring/evaluator.py"
click node_reports "https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/reports/evaluation_report.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_frontend_ui,node_frontend_login,node_frontend_roles,node_user toneBlue
class node_app_entry,node_user_routes,node_document_routes,node_chat_routes,node_auth,node_hashing,node_audit_context,node_classifier,node_sql_handler,node_rag_handler,node_rag_indexing,node_rag_cache toneAmber
class node_sqlite,node_duckdb,node_audit_log toneMint
class node_pipeline,node_dataset,node_answer_eval,node_retrieval_eval,node_security_eval,node_latency_eval,node_vector_eval,node_sql_eval,node_audit_eval,node_reports toneRose
```

## Components

### User interface

- [Frontend pages](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/landing_page.py): `app/DocuFi-Frontend/landing_page.py`
- [Login UI](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/login_handler.py): `app/DocuFi-Frontend/login_handler.py`
- [Role definitions](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/DocuFi-Frontend/roles.py): `app/DocuFi-Frontend/roles.py`

### Assistant application

- [API application](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/main.py): `app/main.py`
- [User administration](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/user_routes.py): `app/routes/user_routes.py`
- [Document management](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/document_routes.py): `app/routes/document_routes.py`
- [Chat routing](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/routes/chat_routes.py): `app/routes/chat_routes.py`
- [Authentication](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/authentication/auth.py): `app/authentication/auth.py`
- [Password hashing](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/authentication/hashing.py): `app/authentication/hashing.py`
- [Request audit context](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/audit_context.py): `app/utils/audit_context.py`
- [Query classifier](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/query_classifier.py): `app/utils/query_classifier.py`
- [Natural-language SQL](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/sql_query.py): `app/utils/sql_query.py`
- [RAG response handler](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/rag_chain.py): `app/utils/rag_chain.py`
- [Document indexing](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/rag_module.py): `app/utils/rag_module.py`
- [RAG response cache](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/response_cache.py): `app/utils/response_cache.py`

### Data and audit

- [User and document store](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/schemas/sqlitedb.py): `app/schemas/sqlitedb.py`
- [Structured data store](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/schemas/duckdb.py): `app/schemas/duckdb.py`
- [Audit event log](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/utils/audit_events.py): `app/utils/audit_events.py`

### Evaluation suite

- [Evaluation pipeline](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/evaluation_pipelines.py): `app/rag_evaluator/evaluation_pipelines.py`
- [Evaluation datasets](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/evaluation_dataset_builder.py): `app/rag_evaluator/evaluation_dataset_builder.py`
- [Answer quality](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/answer_quality/evaluator.py): `app/rag_evaluator/answer_quality/evaluator.py`
- [Retrieval quality](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/retrieval/evaluator.py): `app/rag_evaluator/retrieval/evaluator.py`
- [RBAC security](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/rbac_security/evaluator.py): `app/rag_evaluator/rbac_security/evaluator.py`
- [Latency](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/latency/evaluator.py): `app/rag_evaluator/latency/evaluator.py`
- [Vector DB](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/vector_db/evaluator.py): `app/rag_evaluator/vector_db/evaluator.py`
- [Text-to-SQL](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/text_to_sql/evaluator.py): `app/rag_evaluator/text_to_sql/evaluator.py`
- [Audit monitoring](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/audit_monitoring/evaluator.py): `app/rag_evaluator/audit_monitoring/evaluator.py`
- [Evaluation reports](https://github.com/akg-git/rbac-based-rag-assistant/blob/main/app/rag_evaluator/reports/evaluation_report.py): `app/rag_evaluator/reports/evaluation_report.py`

### Other components

- **Internal user**

## Connections

- Internal user → Frontend pages: uses
- Frontend pages → Login UI: uses (evidence: `app/DocuFi-Frontend/landing_page.py`)
- Frontend pages → Role definitions: uses (evidence: `app/DocuFi-Frontend/landing_page.py`)
- Frontend pages → API application: calls API
- API application → Chat routing: registers (evidence: `app/main.py`)
- API application → Document management: registers (evidence: `app/main.py`)
- API application → User administration: registers (evidence: `app/main.py`)
- User administration → Authentication: authenticates (evidence: `app/routes/user_routes.py`)
- User administration → User and document store: reads/writes (evidence: `app/routes/user_routes.py`)
- Authentication → User and document store: reads credentials (evidence: `app/authentication/auth.py`)
- Authentication → Password hashing: verifies password (evidence: `app/authentication/auth.py`)
- API application → Request audit context: initializes (evidence: `app/main.py`)
- Request audit context → Authentication: authenticates (evidence: `app/utils/audit_context.py`)
- Request audit context → Audit event log: emits events (evidence: `app/utils/audit_context.py`)
- Document management → User and document store: stores metadata (evidence: `app/routes/document_routes.py`)
- Document management → Structured data store: stores table metadata (evidence: `app/routes/document_routes.py`)
- Document management → Document indexing: indexes documents (evidence: `app/routes/document_routes.py`)
- Chat routing → Query classifier: classifies query (evidence: `app/routes/chat_routes.py`)
- Chat routing → Natural-language SQL: routes SQL (evidence: `app/routes/chat_routes.py`)
- Chat routing → RAG response handler: routes RAG/fallback (evidence: `app/routes/chat_routes.py`)
- Natural-language SQL → Structured data store: queries schema (evidence: `app/utils/sql_query.py`)
- Natural-language SQL → RAG response cache: uses cache (evidence: `app/utils/sql_query.py`)
- Natural-language SQL → Audit event log: emits events (evidence: `app/utils/sql_query.py`)
- RAG response handler → Document indexing: invokes RAG chain (evidence: `app/utils/rag_chain.py`)
- RAG response handler → RAG response cache: uses cache (evidence: `app/utils/rag_chain.py`)
- RAG response handler → Audit event log: emits events (evidence: `app/utils/rag_chain.py`)
- Document indexing → User and document store: reads document metadata (evidence: `app/utils/rag_module.py`)
- Evaluation pipeline → Evaluation datasets: builds datasets (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Answer quality: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Retrieval quality: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → RBAC security: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Latency: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Vector DB: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Text-to-SQL: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Audit monitoring: runs evaluation (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
- Evaluation pipeline → Evaluation reports: generates reports (evidence: `app/rag_evaluator/evaluation_pipelines.py`)
