# ramadan-swe/ai-knowledge-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ramadan-swe/ai-knowledge-assistant
- Repository: https://github.com/ramadan-swe/ai-knowledge-assistant

## Overview

AI Knowledge Assistant is a document-grounded Q&A product. Users sign in, upload documents, and ask questions; the backend stores document metadata and chunks, indexes text in a per-user vector collection, then retrieves context and generates an answer asynchronously for chat history. The graph includes authentication, document management, chat/RAG, persistence, and the web interface. README statements establish the broad frontend-to-API and async workflow; source excerpts show backend calls and storage operations. Some frontend component wiring and external service configuration are not visible in the sampled source.

Main entry points: [`backend/app/core/database.py`](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/database.py) (Database sessions), [`backend/app/services/retrieval.py`](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/services/retrieval.py) (RAG processing), [`frontend/lib/api.ts`](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/lib/api.ts) (HTTP client), [`frontend/app/chat/page.tsx`](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/app/chat/page.tsx) (Chat page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_login["Login page<br/>[page.tsx]"]
  node_chatpage["Chat page<br/>[page.tsx]"]
  node_uploadui["File upload<br/>[FileUpload.tsx]"]
  node_doclist["Document list<br/>[DocumentList.tsx]"]
  node_chatui["Chat interface<br/>[ChatUI.tsx]"]
  node_sidebar["Chat sidebar<br/>[Sidebar.tsx]"]
  node_apiclient["HTTP client<br/>[api.ts]"]
end

subgraph group_identity["Identity and API"]
  node_apiapp["API application<br/>[main.py]"]
  node_routes["Route registry<br/>[api.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_authdeps["Token verification<br/>[deps.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
end

subgraph group_knowledge["Knowledge ingestion"]
  node_documents["Document endpoints<br/>[documents.py]"]
  node_ingestion["PDF ingestion<br/>[ingestion.py]"]
end

subgraph group_qa["Chat and retrieval"]
  node_chatendpoint["Chat endpoints<br/>[chat.py]"]
  node_retrieval["RAG processing<br/>[retrieval.py]"]
end

subgraph group_storage["Persistence and AI"]
  node_config["Runtime settings<br/>[config.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_usermodel[("User records<br/>[user.py]")]
  node_docmodel[("Document chunks<br/>[document.py]")]
  node_chatmodel[("Chat records<br/>[chat.py]")]
  node_vectordb[("Chroma vectors")]
  node_llm{{"LLM provider"}}
end

node_user(("User"))

node_user -->|"signs in"| node_login
node_user -->|"uploads files"| node_uploadui
node_user -->|"asks questions"| node_chatpage
node_login -.->|"requests API"| node_apiclient
node_uploadui -.->|"sends upload"| node_apiclient
node_chatpage -.->|"presents chat"| node_chatui
node_chatpage -.->|"shows history"| node_sidebar
node_chatpage -.->|"requests API"| node_apiclient
node_doclist -.->|"requests API"| node_apiclient
node_apiclient -->|"HTTP requests"| node_apiapp
node_apiapp -->|"mounts routes"| node_routes
node_routes -->|"registers routes"| node_auth
node_routes -->|"registers routes"| node_documents
node_routes -->|"registers routes"| node_chatendpoint
node_auth -->|"hashes and signs"| node_security
node_auth -->|"checks current user"| node_authdeps
node_authdeps -->|"decodes token"| node_security
node_authdeps -->|"looks up user"| node_usermodel
node_documents -->|"processes upload"| node_ingestion
node_ingestion -->|"saves documents"| node_docmodel
node_ingestion -->|"stores embeddings"| node_vectordb
node_chatendpoint -->|"creates and processes prompts"| node_retrieval
node_retrieval -->|"retrieves context"| node_vectordb
node_retrieval -->|"generates answer"| node_llm
node_retrieval -->|"updates prompt status"| node_chatmodel
node_auth -->|"uses sessions"| node_database
node_documents -->|"uses sessions"| node_database
node_retrieval -->|"opens background session"| node_database
node_database -->|"loads connection URL"| node_config
node_usermodel -->|"maps tables"| node_database
node_docmodel -->|"maps tables"| node_database
node_chatmodel -->|"maps tables"| node_database
node_retrieval -->|"selects provider settings"| node_llm

click node_login "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/app/login/page.tsx"
click node_chatpage "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/app/chat/page.tsx"
click node_uploadui "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/FileUpload.tsx"
click node_doclist "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/DocumentList.tsx"
click node_chatui "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/ChatUI.tsx"
click node_sidebar "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/Sidebar.tsx"
click node_apiclient "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/lib/api.ts"
click node_apiapp "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/main.py"
click node_routes "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/api.py"
click node_auth "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/auth.py"
click node_authdeps "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/deps.py"
click node_security "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/security.py"
click node_documents "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/documents.py"
click node_ingestion "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/services/ingestion.py"
click node_chatendpoint "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/chat.py"
click node_retrieval "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/services/retrieval.py"
click node_config "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/config.py"
click node_database "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/database.py"
click node_usermodel "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/user.py"
click node_docmodel "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/document.py"
click node_chatmodel "https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/chat.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_login,node_chatpage,node_uploadui,node_doclist,node_chatui,node_sidebar,node_apiclient,node_user toneBlue
class node_apiapp,node_routes,node_auth,node_authdeps,node_security toneAmber
class node_documents,node_ingestion toneMint
class node_chatendpoint,node_retrieval toneRose
class node_config,node_database,node_usermodel,node_docmodel,node_chatmodel,node_vectordb,node_llm toneIndigo
```

## Components

### Web application

- [Login page](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Chat page](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [File upload](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/FileUpload.tsx): `frontend/components/FileUpload.tsx`
- [Document list](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/DocumentList.tsx): `frontend/components/DocumentList.tsx`
- [Chat interface](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/ChatUI.tsx): `frontend/components/ChatUI.tsx`
- [Chat sidebar](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/components/Sidebar.tsx): `frontend/components/Sidebar.tsx`
- [HTTP client](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Identity and API

- [API application](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/main.py): `backend/app/main.py`
- [Route registry](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/api.py): `backend/app/api/api.py`
- [Authentication](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/auth.py): `backend/app/api/endpoints/auth.py`
- [Token verification](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [JWT and passwords](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Knowledge ingestion

- [Document endpoints](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/documents.py): `backend/app/api/endpoints/documents.py`
- [PDF ingestion](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`

### Chat and retrieval

- [Chat endpoints](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/api/endpoints/chat.py): `backend/app/api/endpoints/chat.py`
- [RAG processing](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`

### Persistence and AI

- [Runtime settings](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Database sessions](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [User records](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Document chunks](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/document.py): `backend/app/models/document.py`
- [Chat records](https://github.com/ramadan-swe/ai-knowledge-assistant/blob/main/backend/app/models/chat.py): `backend/app/models/chat.py`
- **Chroma vectors**
- **LLM provider**

### Other components

- **User**

## Connections

- User → Login page: signs in
- User → File upload: uploads files
- User → Chat page: asks questions
- Login page → HTTP client: requests API
- File upload → HTTP client: sends upload
- Chat page → Chat interface: presents chat
- Chat page → Chat sidebar: shows history
- Chat page → HTTP client: requests API
- Document list → HTTP client: requests API
- HTTP client → API application: HTTP requests
- API application → Route registry: mounts routes (evidence: `backend/app/main.py`)
- Route registry → Authentication: registers routes (evidence: `backend/app/api/api.py`)
- Route registry → Document endpoints: registers routes (evidence: `backend/app/api/api.py`)
- Route registry → Chat endpoints: registers routes (evidence: `backend/app/api/api.py`)
- Authentication → JWT and passwords: hashes and signs (evidence: `backend/app/api/endpoints/auth.py`)
- Authentication → Token verification: checks current user (evidence: `backend/app/api/endpoints/auth.py`)
- Token verification → JWT and passwords: decodes token (evidence: `backend/app/api/deps.py`)
- Token verification → User records: looks up user (evidence: `backend/app/api/deps.py`)
- Document endpoints → PDF ingestion: processes upload (evidence: `backend/app/api/endpoints/documents.py`)
- PDF ingestion → Document chunks: saves documents (evidence: `backend/app/services/ingestion.py`)
- PDF ingestion → Chroma vectors: stores embeddings (evidence: `backend/app/services/ingestion.py`)
- Chat endpoints → RAG processing: creates and processes prompts (evidence: `backend/app/api/endpoints/chat.py`)
- RAG processing → Chroma vectors: retrieves context (evidence: `backend/app/services/retrieval.py`)
- RAG processing → LLM provider: generates answer (evidence: `backend/app/services/retrieval.py`)
- RAG processing → Chat records: updates prompt status (evidence: `backend/app/services/retrieval.py`)
- Authentication → Database sessions: uses sessions (evidence: `backend/app/api/endpoints/auth.py`)
- Document endpoints → Database sessions: uses sessions (evidence: `backend/app/api/endpoints/documents.py`)
- RAG processing → Database sessions: opens background session (evidence: `backend/app/services/retrieval.py`)
- Database sessions → Runtime settings: loads connection URL (evidence: `backend/app/core/database.py`)
- User records → Database sessions: maps tables (evidence: `backend/app/models/user.py`)
- Document chunks → Database sessions: maps tables (evidence: `backend/app/models/document.py`)
- Chat records → Database sessions: maps tables (evidence: `backend/app/models/chat.py`)
- RAG processing → LLM provider: selects provider settings (evidence: `backend/app/services/retrieval.py`)
