# ivandrf/rag-manual-searcher architecture

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

- Interactive diagram: https://gitdiagram.com/ivandrf/rag-manual-searcher
- Repository: https://github.com/ivandrf/rag-manual-searcher

## Overview

RAG-manual-searcher is a FastAPI service for authenticated manual search and chat over university math notes, with user registration/login and administrator controls. The main path is a chat request through the API to RAG retrieval, which ranks note chunks and formats a context prompt; the available excerpts do not show the final model-request wiring. Authentication and administration form a separate branch backed by PostgreSQL and Redis. The README provides no further capability detail, and some retrieval modules are represented from the source index rather than inspected excerpts.

Main entry points: [`src/api/auth.py`](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/auth.py) (Auth endpoints), [`src/api/admin.py`](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/admin.py) (Admin endpoints), [`src/api/dependencies.py`](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/dependencies.py) (API dependencies), [`src/app/main.py`](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["FastAPI app<br/>[main.py]"]
  node_chat["Chat endpoint<br/>[chat.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_dependencies["API dependencies<br/>[dependencies.py]"]
  node_utils["API utilities<br/>[utils.py]"]
end

subgraph group_identity["Identity and administration"]
  node_auth["Auth endpoints<br/>[auth.py]"]
  node_admin["Admin endpoints<br/>[admin.py]"]
  node_middleware["Access middleware<br/>[middleware.py]"]
  node_rules["Identity rules<br/>[rules.py]"]
end

subgraph group_retrieval["Manual retrieval"]
  node_rag["RAG prompt builder<br/>[rag.py]"]
  node_bm25["BM25 retrieval<br/>[bm25.py]"]
  node_chunking["Text chunking<br/>[chuncking.py]"]
  node_manuals["Manual text corpus"]
end

subgraph group_persistence["Persistence"]
  node_models["ORM models<br/>[models.py]"]
  node_user_repo["User repository<br/>[user_repo.py]"]
  node_block_repo["Block-list repository<br/>[block_repo.py]"]
  node_pg_connection["PostgreSQL connection<br/>[connection.py]"]
  node_redis_connection["Redis connection<br/>[connection.py]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_caller(("User"))

node_caller -->|"sends requests"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_admin
node_app -->|"registers routes"| node_chat
node_chat -->|"requests retrieval"| node_rag
node_rag -->|"retrieves chunks"| node_bm25
node_bm25 -->|"uses chunks"| node_chunking
node_auth -->|"looks up and adds users"| node_user_repo
node_auth -->|"checks credentials"| node_rules
node_auth -->|"creates token cookies"| node_utils
node_admin -->|"requires admin access"| node_middleware
node_admin -->|"manages users"| node_user_repo
node_admin -->|"updates block list"| node_block_repo
node_middleware -->|"decodes tokens"| node_rules
node_middleware -->|"checks blocked users"| node_block_repo
node_user_repo -->|"queries users"| node_models
node_dependencies -->|"creates session maker"| node_pg_connection
node_dependencies -->|"creates Redis client"| node_redis_connection
node_dependencies -.->|"opens connection"| node_postgres
node_dependencies -.->|"opens connection"| node_redis
node_user_repo -.->|"queries through session"| node_postgres
node_block_repo -.->|"accesses block list"| node_redis
node_chat -->|"uses request schema"| node_schemas
node_auth -->|"uses user schemas"| node_schemas
node_admin -->|"uses admin schemas"| node_schemas

click node_app "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/app/main.py"
click node_chat "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/chat.py"
click node_schemas "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/schemas.py"
click node_dependencies "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/dependencies.py"
click node_auth "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/auth.py"
click node_admin "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/admin.py"
click node_middleware "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/middleware.py"
click node_rules "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/rules.py"
click node_utils "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/utils.py"
click node_models "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/models.py"
click node_user_repo "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/postgresql/user_repo.py"
click node_block_repo "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/redis/block_repo.py"
click node_pg_connection "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/postgresql/connection.py"
click node_redis_connection "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/redis/connection.py"
click node_rag "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/rag.py"
click node_bm25 "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/bm25.py"
click node_chunking "https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/chuncking.py"
click node_manuals "https://github.com/ivandrf/rag-manual-searcher/tree/main/student_book_txt"

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_app,node_chat,node_schemas,node_dependencies,node_utils,node_caller toneBlue
class node_auth,node_admin,node_middleware,node_rules toneAmber
class node_rag,node_bm25,node_chunking,node_manuals toneMint
class node_models,node_user_repo,node_block_repo,node_pg_connection,node_redis_connection,node_postgres,node_redis toneRose
```

## Components

### API and access

- [FastAPI app](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/app/main.py): `src/app/main.py`
- [Chat endpoint](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/chat.py): `src/api/chat.py`
- [API schemas](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/schemas.py): `src/domain/schemas.py`
- [API dependencies](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/dependencies.py): `src/api/dependencies.py`
- [API utilities](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/utils.py): `src/api/utils.py`

### Identity and administration

- [Auth endpoints](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/auth.py): `src/api/auth.py`
- [Admin endpoints](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/admin.py): `src/api/admin.py`
- [Access middleware](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/api/middleware.py): `src/api/middleware.py`
- [Identity rules](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/rules.py): `src/domain/rules.py`

### Manual retrieval

- [RAG prompt builder](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/rag.py): `src/infrastructure/rag/rag.py`
- [BM25 retrieval](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/bm25.py): `src/infrastructure/rag/bm25.py`
- [Text chunking](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/rag/chuncking.py): `src/infrastructure/rag/chuncking.py`
- [Manual text corpus](https://github.com/ivandrf/rag-manual-searcher/tree/main/student_book_txt): `student_book_txt`

### Persistence

- [ORM models](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/domain/models.py): `src/domain/models.py`
- [User repository](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/postgresql/user_repo.py): `src/infrastructure/repository/postgresql/user_repo.py`
- [Block-list repository](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/redis/block_repo.py): `src/infrastructure/repository/redis/block_repo.py`
- [PostgreSQL connection](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/postgresql/connection.py): `src/infrastructure/repository/postgresql/connection.py`
- [Redis connection](https://github.com/ivandrf/rag-manual-searcher/blob/main/src/infrastructure/repository/redis/connection.py): `src/infrastructure/repository/redis/connection.py`
- **PostgreSQL**
- **Redis**

### Other components

- **User**

## Connections

- User → FastAPI app: sends requests
- FastAPI app → Auth endpoints: registers routes (evidence: `src/app/main.py`)
- FastAPI app → Admin endpoints: registers routes (evidence: `src/app/main.py`)
- FastAPI app → Chat endpoint: registers routes (evidence: `src/app/main.py`)
- Chat endpoint → RAG prompt builder: requests retrieval (evidence: `src/api/chat.py`)
- RAG prompt builder → BM25 retrieval: retrieves chunks (evidence: `src/infrastructure/rag/rag.py`)
- BM25 retrieval → Text chunking: uses chunks (evidence: `src/infrastructure/rag/bm25.py`)
- Auth endpoints → User repository: looks up and adds users (evidence: `src/api/auth.py`)
- Auth endpoints → Identity rules: checks credentials (evidence: `src/api/auth.py`)
- Auth endpoints → API utilities: creates token cookies (evidence: `src/api/auth.py`)
- Admin endpoints → Access middleware: requires admin access (evidence: `src/api/admin.py`)
- Admin endpoints → User repository: manages users (evidence: `src/api/admin.py`)
- Admin endpoints → Block-list repository: updates block list (evidence: `src/api/admin.py`)
- Access middleware → Identity rules: decodes tokens (evidence: `src/api/middleware.py`)
- Access middleware → Block-list repository: checks blocked users (evidence: `src/api/middleware.py`)
- User repository → ORM models: queries users (evidence: `src/infrastructure/repository/postgresql/user_repo.py`)
- API dependencies → PostgreSQL connection: creates session maker (evidence: `src/api/dependencies.py`)
- API dependencies → Redis connection: creates Redis client (evidence: `src/api/dependencies.py`)
- API dependencies → PostgreSQL: opens connection
- API dependencies → Redis: opens connection
- User repository → PostgreSQL: queries through session
- Block-list repository → Redis: accesses block list
- Chat endpoint → API schemas: uses request schema (evidence: `src/api/chat.py`)
- Auth endpoints → API schemas: uses user schemas (evidence: `src/api/auth.py`)
- Admin endpoints → API schemas: uses admin schemas (evidence: `src/api/admin.py`)
