# shauryadusht/sentinel-rag architecture

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

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

## Overview

Secure Multi-Tenant RAG is a FastAPI application for tenant-scoped document ingestion and question answering. Users authenticate into an organisation; uploaded documents are validated, parsed, chunked, embedded and stored with access metadata. Queries pass through the route and RAG service, where a per-user cache may satisfy the request; otherwise retrieval applies role-derived filters and a second authorization check before approved context is sent to an LLM. The API also supports organisation/user management, document deletion, and query auditing. Wiring for unsampled routes and components is limited to documented capabilities.

Main entry points: [`app/ingestion/service.py`](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/service.py) (Ingestion orchestrator), [`app/main.py`](https://github.com/shauryadusht/sentinel-rag/blob/main/app/main.py) (FastAPI app), [`app/rag/service.py`](https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/service.py) (RAG service), [`app/retrieval/service.py`](https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/service.py) (Retrieval orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_application["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_user_routes["Org and user routes<br/>[users.py]"]
  node_auth_middleware["JWT middleware<br/>[auth.py]"]
  node_user_service["User service<br/>[user_service.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_documents_route["Document routes<br/>[documents.py]"]
  node_ingestion["Ingestion orchestrator<br/>[service.py]"]
  node_validator["Document validator<br/>[validator.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_chunker["Text chunker<br/>[chunker.py]"]
  node_embedder["Text embedder<br/>[embedder.py]"]
end

subgraph group_query["Secure RAG query"]
  node_query_route["Query route<br/>[query.py]"]
  node_rag_service["RAG service<br/>[service.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_retrieval["Retrieval orchestrator<br/>[service.py]"]
  node_scope["Role scope resolver<br/>[scope_resolver.py]"]
  node_filters["Search filter builder<br/>[filter_builder.py]"]
  node_assembler["Context authorization"]
  node_prompt["Prompt builder<br/>[prompt_builder.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_state["Persistence and audit"]
  node_vector_store[("Chroma vector store<br/>[vector_store.py]")]
  node_relational[("SQL database<br/>[session.py]")]
  node_audit["Audit service<br/>[audit_service.py]"]
end

node_user(("API user"))
node_llm_provider(("LLM provider"))
node_redis[("Redis cache")]

node_user -->|"sends requests"| node_application
node_application -->|"dispatches auth"| node_auth_routes
node_application -->|"dispatches org"| node_user_routes
node_application -->|"dispatches documents"| node_documents_route
node_application -->|"dispatches queries"| node_query_route
node_application -->|"installs middleware"| node_auth_middleware
node_auth_middleware -->|"permits public paths"| node_auth_routes
node_auth_middleware -->|"attaches user context"| node_user_routes
node_auth_middleware -->|"attaches user context"| node_documents_route
node_auth_middleware -->|"attaches user context"| node_query_route
node_auth_routes -->|"authenticates users"| node_user_service
node_user_routes -->|"manages organisations"| node_user_service
node_user_service -->|"reads and writes"| node_relational
node_documents_route -->|"ingests or deletes"| node_ingestion
node_ingestion -->|"validates input"| node_validator
node_ingestion -->|"parses documents"| node_parser
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embedder
node_ingestion -->|"upserts or deletes"| node_vector_store
node_ingestion -->|"writes audit records"| node_relational
node_query_route -->|"runs query"| node_rag_service
node_rag_service -->|"checks and sets"| node_cache
node_cache -->|"reads and writes"| node_redis
node_rag_service -->|"requests secure retrieval"| node_retrieval
node_retrieval -->|"resolves role scope"| node_scope
node_retrieval -->|"embeds query"| node_embedder
node_retrieval -->|"builds search filter"| node_filters
node_retrieval -->|"searches chunks"| node_vector_store
node_retrieval -->|"checks retrieved chunks"| node_assembler
node_rag_service -->|"builds prompt"| node_prompt
node_rag_service -->|"generates answer"| node_llm
node_llm -->|"sends prompt"| node_llm_provider
node_rag_service -->|"records query"| node_audit
node_audit -->|"writes audit record"| node_relational

click node_application "https://github.com/shauryadusht/sentinel-rag/blob/main/app/main.py"
click node_auth_routes "https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/auth.py"
click node_user_routes "https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/users.py"
click node_auth_middleware "https://github.com/shauryadusht/sentinel-rag/blob/main/app/middleware/auth.py"
click node_user_service "https://github.com/shauryadusht/sentinel-rag/blob/main/app/services/user_service.py"
click node_documents_route "https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/documents.py"
click node_ingestion "https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/service.py"
click node_validator "https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/validator.py"
click node_parser "https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/parser.py"
click node_chunker "https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/chunker.py"
click node_embedder "https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/embedder.py"
click node_query_route "https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/query.py"
click node_rag_service "https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/service.py"
click node_cache "https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/cache.py"
click node_retrieval "https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/service.py"
click node_scope "https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/scope_resolver.py"
click node_filters "https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/filter_builder.py"
click node_assembler "https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/context_assembler.py"
click node_prompt "https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/prompt_builder.py"
click node_llm "https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/llm_client.py"
click node_vector_store "https://github.com/shauryadusht/sentinel-rag/blob/main/app/db/vector_store.py"
click node_relational "https://github.com/shauryadusht/sentinel-rag/blob/main/app/db/session.py"
click node_audit "https://github.com/shauryadusht/sentinel-rag/blob/main/app/services/audit_service.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_application,node_auth_routes,node_user_routes,node_auth_middleware,node_user_service,node_user toneBlue
class node_documents_route,node_ingestion,node_validator,node_parser,node_chunker,node_embedder,node_redis toneAmber
class node_query_route,node_rag_service,node_cache,node_retrieval,node_scope,node_filters,node_assembler,node_prompt,node_llm toneMint
class node_vector_store,node_relational,node_audit toneRose
class node_llm_provider toneIndigo
```

## Components

### API and identity

- [FastAPI app](https://github.com/shauryadusht/sentinel-rag/blob/main/app/main.py): `app/main.py`
- [Auth routes](https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Org and user routes](https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/users.py): `app/api/routes/users.py`
- [JWT middleware](https://github.com/shauryadusht/sentinel-rag/blob/main/app/middleware/auth.py): `app/middleware/auth.py`
- [User service](https://github.com/shauryadusht/sentinel-rag/blob/main/app/services/user_service.py): `app/services/user_service.py`

### Document ingestion

- [Document routes](https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/documents.py): `app/api/routes/documents.py`
- [Ingestion orchestrator](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/service.py): `app/ingestion/service.py`
- [Document validator](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/validator.py): `app/ingestion/validator.py`
- [Document parser](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/parser.py): `app/ingestion/parser.py`
- [Text chunker](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/chunker.py): `app/ingestion/chunker.py`
- [Text embedder](https://github.com/shauryadusht/sentinel-rag/blob/main/app/ingestion/embedder.py): `app/ingestion/embedder.py`

### Secure RAG query

- [Query route](https://github.com/shauryadusht/sentinel-rag/blob/main/app/api/routes/query.py): `app/api/routes/query.py`
- [RAG service](https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/service.py): `app/rag/service.py`
- [Response cache](https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/cache.py): `app/rag/cache.py`
- [Retrieval orchestrator](https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/service.py): `app/retrieval/service.py`
- [Role scope resolver](https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/scope_resolver.py): `app/retrieval/scope_resolver.py`
- [Search filter builder](https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/filter_builder.py): `app/retrieval/filter_builder.py`
- [Context authorization](https://github.com/shauryadusht/sentinel-rag/blob/main/app/retrieval/context_assembler.py): `app/retrieval/context_assembler.py`
- [Prompt builder](https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/prompt_builder.py): `app/rag/prompt_builder.py`
- [LLM client](https://github.com/shauryadusht/sentinel-rag/blob/main/app/rag/llm_client.py): `app/rag/llm_client.py`

### Persistence and audit

- [Chroma vector store](https://github.com/shauryadusht/sentinel-rag/blob/main/app/db/vector_store.py): `app/db/vector_store.py`
- [SQL database](https://github.com/shauryadusht/sentinel-rag/blob/main/app/db/session.py): `app/db/session.py`
- [Audit service](https://github.com/shauryadusht/sentinel-rag/blob/main/app/services/audit_service.py): `app/services/audit_service.py`

### Other components

- **API user**
- **LLM provider**
- **Redis cache**

## Connections

- API user → FastAPI app: sends requests
- FastAPI app → Auth routes: dispatches auth
- FastAPI app → Org and user routes: dispatches org
- FastAPI app → Document routes: dispatches documents
- FastAPI app → Query route: dispatches queries
- FastAPI app → JWT middleware: installs middleware
- JWT middleware → Auth routes: permits public paths
- JWT middleware → Org and user routes: attaches user context
- JWT middleware → Document routes: attaches user context
- JWT middleware → Query route: attaches user context
- Auth routes → User service: authenticates users
- Org and user routes → User service: manages organisations
- User service → SQL database: reads and writes
- Document routes → Ingestion orchestrator: ingests or deletes
- Ingestion orchestrator → Document validator: validates input
- Ingestion orchestrator → Document parser: parses documents
- Ingestion orchestrator → Text chunker: chunks text
- Ingestion orchestrator → Text embedder: embeds chunks
- Ingestion orchestrator → Chroma vector store: upserts or deletes
- Ingestion orchestrator → SQL database: writes audit records
- Query route → RAG service: runs query
- RAG service → Response cache: checks and sets
- Response cache → Redis cache: reads and writes
- RAG service → Retrieval orchestrator: requests secure retrieval
- Retrieval orchestrator → Role scope resolver: resolves role scope
- Retrieval orchestrator → Text embedder: embeds query
- Retrieval orchestrator → Search filter builder: builds search filter
- Retrieval orchestrator → Chroma vector store: searches chunks
- Retrieval orchestrator → Context authorization: checks retrieved chunks
- RAG service → Prompt builder: builds prompt
- RAG service → LLM client: generates answer
- LLM client → LLM provider: sends prompt
- RAG service → Audit service: records query
- Audit service → SQL database: writes audit record