# sanathhh05/ai_knowledge_agent architecture

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

- Interactive diagram: https://gitdiagram.com/sanathhh05/ai_knowledge_agent
- Repository: https://github.com/sanathhh05/ai_knowledge_agent

## Overview

RAMBO lets authenticated users build a private knowledge base from files, web pages, and YouTube videos, then ask questions in text or voice and receive cited answers. Ingestion extracts and chunks content, embeds it, and stores it for user-scoped retrieval; chat combines retrieved context with conversation history for local-model generation. The graph includes authentication, source ingestion, retrieval, chat, and frontend interaction. Some subsystem wiring is documented in the README or SOURCE INDEX rather than shown in excerpts; unsampled links are omitted where ownership is unclear.

Main entry points: [`backend/app/database.py`](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/database.py) (Database sessions), [`backend/app/services/ingestion_service.py`](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/ingestion_service.py) (Ingestion orchestration), [`frontend/app/chat/page.tsx`](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/app/chat/page.tsx) (Chat page), [`backend/app/routers/auth.py`](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/auth.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_chat_ui["Chat page<br/>[page.tsx]"]
  node_chat_api["Chat API client<br/>[chat.ts]"]
  node_chat_components["Chat components<br/>[MessageBubble.tsx]"]
  node_sources_ui["Sources page<br/>[page.tsx]"]
end

subgraph group_identity["Authentication"]
  node_auth_router["Auth endpoints<br/>[auth.py]"]
  node_security["JWT and password security<br/>[security.py]"]
end

subgraph group_ingestion["Source ingestion"]
  node_source_router["Source endpoints<br/>[sources.py]"]
  node_ingestion_service["Ingestion orchestration"]
  node_extractors["Format extractors<br/>[pdf_service.py]"]
  node_chunking["Text chunking"]
  node_embedding["Embedding service"]
end

subgraph group_chat["Retrieval and chat"]
  node_conversation_router["Conversation endpoints<br/>[conversations.py]"]
  node_stt["Speech transcription<br/>[stt_service.py]"]
  node_rag["RAG orchestration<br/>[rag_service.py]"]
  node_vector_search["Vector search"]
  node_llm["Answer generation<br/>[llm_service.py]"]
end

subgraph group_persistence["Data persistence"]
  node_database[("Database sessions<br/>[database.py]")]
  node_user_model["User records<br/>[user.py]"]
  node_source_model["Source records<br/>[source.py]"]
  node_chunk_model["Chunk records<br/>[chunk.py]"]
  node_chat_model["Conversation records<br/>[chat.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL and pgvector")]
node_ollama{{"Ollama local models"}}
node_browser["Browser speech APIs"]

node_user -->|"asks questions"| node_chat_ui
node_chat_ui -->|"calls"| node_chat_api
node_chat_ui -->|"renders"| node_chat_components
node_chat_api -->|"sends requests"| node_conversation_router
node_user -->|"adds sources"| node_sources_ui
node_user -->|"signs in"| node_auth_router
node_auth_router -->|"hashes and signs"| node_security
node_auth_router -->|"reads and writes"| node_user_model
node_auth_router -->|"gets session"| node_database
node_source_router -->|"invokes ingestion"| node_ingestion_service
node_ingestion_service -->|"dispatches extraction"| node_extractors
node_ingestion_service -->|"chunks text"| node_chunking
node_ingestion_service -->|"embeds chunks"| node_embedding
node_ingestion_service -->|"creates and updates"| node_source_model
node_ingestion_service -->|"stores chunks"| node_chunk_model
node_embedding -->|"requests vectors"| node_ollama
node_source_router -->|"gets session"| node_database
node_conversation_router -->|"transcribes audio"| node_stt
node_conversation_router -->|"processes turn"| node_rag
node_conversation_router -->|"gets session"| node_database
node_rag -->|"retrieves chunks"| node_vector_search
node_rag -->|"generates answer"| node_llm
node_rag -->|"stores messages"| node_chat_model
node_vector_search -->|"embeds query"| node_embedding
node_vector_search -->|"queries chunks"| node_chunk_model
node_vector_search -->|"joins sources"| node_source_model
node_llm -->|"requests generation"| node_ollama
node_database -->|"connects to"| node_postgres
node_user_model -->|"persists in"| node_database
node_source_model -->|"persists in"| node_database
node_chunk_model -->|"persists in"| node_database
node_chat_model -->|"persists in"| node_database
node_chat_ui -.->|"records and plays audio"| node_browser

click node_chat_ui "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/app/chat/page.tsx"
click node_chat_api "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/lib/api/chat.ts"
click node_chat_components "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/components/Chat/MessageBubble.tsx"
click node_sources_ui "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/app/sources/page.tsx"
click node_auth_router "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/auth.py"
click node_security "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/utils/security.py"
click node_source_router "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/sources.py"
click node_ingestion_service "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/ingestion_service.py"
click node_extractors "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/pdf_service.py"
click node_chunking "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/chunking_service.py"
click node_embedding "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/embedding_service.py"
click node_conversation_router "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/conversations.py"
click node_stt "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/stt_service.py"
click node_rag "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/rag_service.py"
click node_vector_search "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/vector_search_service.py"
click node_llm "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/llm_service.py"
click node_database "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/database.py"
click node_user_model "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/user.py"
click node_source_model "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/source.py"
click node_chunk_model "https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/chunk.py"
click node_chat_model "https://github.com/sanathhh05/ai_knowledge_agent/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_chat_ui,node_chat_api,node_chat_components,node_sources_ui,node_user,node_browser toneBlue
class node_auth_router,node_security,node_postgres toneAmber
class node_source_router,node_ingestion_service,node_extractors,node_chunking,node_embedding toneMint
class node_conversation_router,node_stt,node_rag,node_vector_search,node_llm toneRose
class node_database,node_user_model,node_source_model,node_chunk_model,node_chat_model,node_ollama toneIndigo
```

## Components

### User interface

- [Chat page](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [Chat API client](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/lib/api/chat.ts): `frontend/lib/api/chat.ts`
- [Chat components](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/components/Chat/MessageBubble.tsx): `frontend/components/Chat/MessageBubble.tsx`
- [Sources page](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/frontend/app/sources/page.tsx): `frontend/app/sources/page.tsx`

### Authentication

- [Auth endpoints](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [JWT and password security](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/utils/security.py): `backend/app/utils/security.py`

### Source ingestion

- [Source endpoints](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/sources.py): `backend/app/routers/sources.py`
- [Ingestion orchestration](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Format extractors](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Text chunking](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/chunking_service.py): `backend/app/services/chunking_service.py`
- [Embedding service](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`

### Retrieval and chat

- [Conversation endpoints](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/routers/conversations.py): `backend/app/routers/conversations.py`
- [Speech transcription](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/stt_service.py): `backend/app/services/stt_service.py`
- [RAG orchestration](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Vector search](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/vector_search_service.py): `backend/app/services/vector_search_service.py`
- [Answer generation](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`

### Data persistence

- [Database sessions](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/database.py): `backend/app/database.py`
- [User records](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Source records](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/source.py): `backend/app/models/source.py`
- [Chunk records](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/chunk.py): `backend/app/models/chunk.py`
- [Conversation records](https://github.com/sanathhh05/ai_knowledge_agent/blob/main/backend/app/models/chat.py): `backend/app/models/chat.py`

### Other components

- **User**
- **PostgreSQL and pgvector**
- **Ollama local models**
- **Browser speech APIs**

## Connections

- User → Chat page: asks questions
- Chat page → Chat API client: calls (evidence: `frontend/app/chat/page.tsx`)
- Chat page → Chat components: renders (evidence: `frontend/app/chat/page.tsx`)
- Chat API client → Conversation endpoints: sends requests (evidence: `frontend/lib/api/chat.ts`)
- User → Sources page: adds sources
- User → Auth endpoints: signs in
- Auth endpoints → JWT and password security: hashes and signs (evidence: `backend/app/routers/auth.py`)
- Auth endpoints → User records: reads and writes (evidence: `backend/app/routers/auth.py`)
- Auth endpoints → Database sessions: gets session (evidence: `backend/app/routers/auth.py`)
- Source endpoints → Ingestion orchestration: invokes ingestion (evidence: `backend/app/routers/sources.py`)
- Ingestion orchestration → Format extractors: dispatches extraction (evidence: `backend/app/services/ingestion_service.py`)
- Ingestion orchestration → Text chunking: chunks text (evidence: `backend/app/services/ingestion_service.py`)
- Ingestion orchestration → Embedding service: embeds chunks (evidence: `backend/app/services/ingestion_service.py`)
- Ingestion orchestration → Source records: creates and updates (evidence: `backend/app/services/ingestion_service.py`)
- Ingestion orchestration → Chunk records: stores chunks (evidence: `backend/app/services/ingestion_service.py`)
- Embedding service → Ollama local models: requests vectors (evidence: `backend/app/services/embedding_service.py`)
- Source endpoints → Database sessions: gets session (evidence: `backend/app/routers/sources.py`)
- Conversation endpoints → Speech transcription: transcribes audio (evidence: `backend/app/routers/conversations.py`)
- Conversation endpoints → RAG orchestration: processes turn (evidence: `backend/app/routers/conversations.py`)
- Conversation endpoints → Database sessions: gets session (evidence: `backend/app/routers/conversations.py`)
- RAG orchestration → Vector search: retrieves chunks (evidence: `backend/app/services/rag_service.py`)
- RAG orchestration → Answer generation: generates answer (evidence: `backend/app/services/rag_service.py`)
- RAG orchestration → Conversation records: stores messages (evidence: `backend/app/services/rag_service.py`)
- Vector search → Embedding service: embeds query (evidence: `backend/app/services/vector_search_service.py`)
- Vector search → Chunk records: queries chunks (evidence: `backend/app/services/vector_search_service.py`)
- Vector search → Source records: joins sources (evidence: `backend/app/services/vector_search_service.py`)
- Answer generation → Ollama local models: requests generation (evidence: `backend/app/services/llm_service.py`)
- Database sessions → PostgreSQL and pgvector: connects to (evidence: `backend/app/database.py`)
- User records → Database sessions: persists in (evidence: `backend/app/models/user.py`)
- Source records → Database sessions: persists in (evidence: `backend/app/models/source.py`)
- Chunk records → Database sessions: persists in (evidence: `backend/app/models/chunk.py`)
- Conversation records → Database sessions: persists in (evidence: `backend/app/models/chat.py`)
- Chat page → Browser speech APIs: records and plays audio
