# gelevanog/permission-aware-rag architecture

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

- Interactive diagram: https://gitdiagram.com/gelevanog/permission-aware-rag
- Repository: https://github.com/gelevanog/permission-aware-rag

## Overview

Clearance is a private, permission-aware company document RAG. Employees ask questions through the API; verified identity principals scope vector retrieval before ranking, and PostgreSQL row-level security independently restricts rows. Retrieved text is passed to a configured chat model, with audit records of usage. Documents enter through local folders or cloud connectors, then parsing, chunking, embedding, and ACL indexing. The README also describes admin, audit, and evaluation capabilities. Several implementation links below are dashed where the supplied excerpts do not establish the call path.

Main entry points: [`src/clearance/index.py`](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/index.py) (Index writer), [`src/clearance/assistant.py`](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/assistant.py) (RAG assistant), [`src/clearance/api/app.py`](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/api/app.py) (HTTP API), [`src/clearance/retrieval/search.py`](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/retrieval/search.py) (Permission-filtered search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_localdocs["Local files<br/>[local.py]"]
  node_cloudconnectors["Drive and SharePoint"]
  node_parser["Document parser<br/>[parsing.py]"]
  node_chunker["Section chunker<br/>[chunking.py]"]
  node_indexer["Index writer<br/>[index.py]"]
end

subgraph group_security["Identity and permissions"]
  node_acl["ACL rules<br/>[acl.py]"]
  node_auth["Token identity<br/>[tokens.py]"]
  node_groupmap["Group mapping<br/>[mapping.py]"]
end

subgraph group_answer["Answer runtime"]
  node_embedder["Embeddings<br/>[embeddings.py]"]
  node_assistant["RAG assistant<br/>[assistant.py]"]
  node_retriever["Permission-filtered search<br/>[search.py]"]
  node_cache["Retrieval cache<br/>[cache.py]"]
  node_model["Chat model<br/>[base.py]"]
  node_database[("PostgreSQL and pgvector<br/>[session.py]")]
end

subgraph group_interfaces["Interfaces and operations"]
  node_audit["Audit log<br/>[audit.py]"]
  node_api["HTTP API<br/>[app.py]"]
  node_web["Web API client<br/>[api.ts]"]
  node_admin["Admin and audit UI<br/>[page.tsx]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation runner<br/>[runner.py]"]
  node_evalui["Evaluation UI<br/>[page.tsx]"]
end

node_employee(("Employee"))
node_idp["Identity provider"]

node_employee -->|"asks"| node_api
node_api -->|"calls"| node_assistant
node_assistant -.->|"embeds query"| node_embedder
node_assistant -.->|"searches"| node_retriever
node_assistant -.->|"generates answer"| node_model
node_assistant -.->|"uses cache"| node_cache
node_assistant -.->|"records usage"| node_audit
node_retriever -->|"queries securely"| node_database
node_retriever -->|"filters principals"| node_acl
node_auth -->|"maps groups"| node_groupmap
node_idp -.->|"issues claims"| node_auth
node_localdocs -.->|"supplies documents"| node_indexer
node_cloudconnectors -.->|"syncs documents"| node_indexer
node_indexer -->|"parses content"| node_parser
node_indexer -->|"chunks sections"| node_chunker
node_indexer -->|"embeds chunks"| node_embedder
node_indexer -->|"writes permissions"| node_acl
node_indexer -->|"writes index"| node_database
node_web -.->|"calls endpoints"| node_api
node_admin -.->|"uses client"| node_web
node_evalui -.->|"uses evaluation API"| node_api
node_eval -->|"evaluates answers"| node_assistant

click node_localdocs "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/connectors/local.py"
click node_cloudconnectors "https://github.com/gelevanog/permission-aware-rag/tree/main/src/clearance/connectors"
click node_parser "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/ingest/parsing.py"
click node_chunker "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/ingest/chunking.py"
click node_indexer "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/index.py"
click node_embedder "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/embeddings.py"
click node_acl "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/acl.py"
click node_auth "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/auth/tokens.py"
click node_groupmap "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/auth/mapping.py"
click node_assistant "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/assistant.py"
click node_retriever "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/retrieval/search.py"
click node_cache "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/retrieval/cache.py"
click node_model "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/llm/base.py"
click node_database "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/db/session.py"
click node_audit "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/audit.py"
click node_api "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/api/app.py"
click node_web "https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/lib/api.ts"
click node_admin "https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/app/admin/page.tsx"
click node_eval "https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/eval/runner.py"
click node_evalui "https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/app/eval/page.tsx"

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_localdocs,node_cloudconnectors,node_parser,node_chunker,node_indexer toneBlue
class node_acl,node_auth,node_groupmap toneAmber
class node_embedder,node_assistant,node_retriever,node_cache,node_model,node_database toneMint
class node_audit,node_api,node_web,node_admin toneRose
class node_eval,node_evalui,node_employee,node_idp toneIndigo
```

## Components

### Document ingestion

- [Local files](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/connectors/local.py): `src/clearance/connectors/local.py`
- [Drive and SharePoint](https://github.com/gelevanog/permission-aware-rag/tree/main/src/clearance/connectors): `src/clearance/connectors`
- [Document parser](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/ingest/parsing.py): `src/clearance/ingest/parsing.py`
- [Section chunker](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/ingest/chunking.py): `src/clearance/ingest/chunking.py`
- [Index writer](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/index.py): `src/clearance/index.py`

### Identity and permissions

- [ACL rules](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/acl.py): `src/clearance/acl.py`
- [Token identity](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/auth/tokens.py): `src/clearance/auth/tokens.py`
- [Group mapping](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/auth/mapping.py): `src/clearance/auth/mapping.py`

### Answer runtime

- [Embeddings](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/embeddings.py): `src/clearance/embeddings.py`
- [RAG assistant](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/assistant.py): `src/clearance/assistant.py`
- [Permission-filtered search](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/retrieval/search.py): `src/clearance/retrieval/search.py`
- [Retrieval cache](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/retrieval/cache.py): `src/clearance/retrieval/cache.py`
- [Chat model](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/llm/base.py): `src/clearance/llm/base.py`
- [PostgreSQL and pgvector](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/db/session.py): `src/clearance/db/session.py`

### Interfaces and operations

- [Audit log](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/audit.py): `src/clearance/audit.py`
- [HTTP API](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/api/app.py): `src/clearance/api/app.py`
- [Web API client](https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Admin and audit UI](https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/app/admin/page.tsx): `web/src/app/admin/page.tsx`

### Evaluation

- [Evaluation runner](https://github.com/gelevanog/permission-aware-rag/blob/main/src/clearance/eval/runner.py): `src/clearance/eval/runner.py`
- [Evaluation UI](https://github.com/gelevanog/permission-aware-rag/blob/main/web/src/app/eval/page.tsx): `web/src/app/eval/page.tsx`

### Other components

- **Employee**
- **Identity provider**

## Connections

- Employee → HTTP API: asks (evidence: `src/clearance/api/app.py`)
- HTTP API → RAG assistant: calls (evidence: `src/clearance/api/app.py`)
- RAG assistant → Embeddings: embeds query (evidence: `src/clearance/assistant.py`)
- RAG assistant → Permission-filtered search: searches (evidence: `src/clearance/assistant.py`)
- RAG assistant → Chat model: generates answer (evidence: `src/clearance/assistant.py`)
- RAG assistant → Retrieval cache: uses cache (evidence: `src/clearance/assistant.py`)
- RAG assistant → Audit log: records usage (evidence: `src/clearance/assistant.py`)
- Permission-filtered search → PostgreSQL and pgvector: queries securely (evidence: `src/clearance/retrieval/search.py`)
- Permission-filtered search → ACL rules: filters principals (evidence: `src/clearance/retrieval/search.py`)
- Token identity → Group mapping: maps groups (evidence: `src/clearance/auth/tokens.py`)
- Identity provider → Token identity: issues claims
- Local files → Index writer: supplies documents (evidence: `src/clearance/connectors/local.py`)
- Drive and SharePoint → Index writer: syncs documents (evidence: `src/clearance/connectors/local.py`)
- Index writer → Document parser: parses content (evidence: `src/clearance/index.py`)
- Index writer → Section chunker: chunks sections (evidence: `src/clearance/index.py`)
- Index writer → Embeddings: embeds chunks (evidence: `src/clearance/index.py`)
- Index writer → ACL rules: writes permissions (evidence: `src/clearance/index.py`)
- Index writer → PostgreSQL and pgvector: writes index (evidence: `src/clearance/index.py`)
- Web API client → HTTP API: calls endpoints
- Admin and audit UI → Web API client: uses client
- Evaluation UI → HTTP API: uses evaluation API
- Evaluation runner → RAG assistant: evaluates answers (evidence: `src/clearance/eval/runner.py`)
