# lkmbh42/agentic_rag_claudecode architecture

> Architecture diagram of the GitHub repository lkmbh42/agentic_rag_claudecode, 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/lkmbh42/agentic_rag_claudecode
- Repository: https://github.com/lkmbh42/agentic_rag_claudecode

## Overview

This is a private, multi-user Agentic RAG platform with a React admin/chat UI, FastAPI backend, background indexing/evaluation worker, and self-hosted model services. The main workflow is authenticated document upload → queued parsing and indexing → permission-scoped retrieval → agent answer with citations, streamed to the user. Separate capabilities cover administration, visual-document handling, and evaluation/observability. The README documents the broader architecture; some subsystem links below reflect those documented responsibilities because their implementation was not sampled.

Main entry points: [`app/main.py`](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/main.py) (FastAPI application), [`app/ingestion/indexer.py`](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/indexer.py) (Document indexer), [`admin-ui/app/src/App.tsx`](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/App.tsx) (Admin and chat UI), [`app/retrieval/retriever.py`](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/retrieval/retriever.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_ui["Admin and chat UI<br/>[App.tsx]"]
  node_ui_chat["Chat interface<br/>[Chat.tsx]"]
  node_ui_admin["Admin interface<br/>[Admin.tsx]"]
  node_api_client["UI API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth["Authentication and access control<br/>[auth.py]"]
  node_document_api["Document endpoints<br/>[documents.py]"]
  node_search_api["Search endpoints<br/>[search.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_admin_api["Admin endpoints<br/>[admin.py]"]
end

subgraph group_knowledge["Knowledge pipeline"]
  node_worker["Background worker<br/>[main.py]"]
  node_queue["Redis job queues<br/>[queue.py]"]
  node_indexer["Document indexer<br/>[indexer.py]"]
  node_pipeline["Parse and chunk<br/>[pipeline.py]"]
  node_file_storage["Uploaded-file storage<br/>[storage.py]"]
  node_visual["Visual document services<br/>[main.py]"]
  node_db[("PostgreSQL<br/>[session.py]")]
end

subgraph group_answering["Retrieval and answers"]
  node_retrieval["Hybrid retrieval<br/>[retriever.py]"]
  node_agent["Agent graph<br/>[runtime.py]"]
  node_llm["LLM client<br/>[client.py]"]
  node_embeddings["Embedding and reranking service<br/>[main.py]"]
  node_visual_search["Visual retrieval service<br/>[main.py]"]
  node_qdrant[("Qdrant vector store<br/>[qdrant_index.py]")]
end

subgraph group_operations["Operations and evaluation"]
  node_evaluation["Evaluation and judging<br/>[runner.py]"]
  node_tracing["Tracing and metrics<br/>[tracing.py]"]
end

node_user(("Employee"))
node_admin(("Administrator"))
node_phoenix["Phoenix"]

node_user -->|"uses"| node_ui
node_admin -->|"uses"| node_ui
node_ui -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_backend
node_ui -->|"shows"| node_ui_chat
node_ui -->|"shows"| node_ui_admin
node_backend -->|"dispatches"| node_auth
node_backend -->|"dispatches"| node_document_api
node_backend -->|"dispatches"| node_search_api
node_backend -->|"dispatches"| node_chat_api
node_backend -->|"dispatches"| node_admin_api
node_document_api -->|"stores uploads"| node_file_storage
node_document_api -->|"enqueues indexing"| node_queue
node_worker -->|"consumes jobs"| node_queue
node_worker -->|"indexes documents"| node_indexer
node_indexer -->|"reads uploads"| node_file_storage
node_indexer -->|"parses and chunks"| node_pipeline
node_pipeline -.->|"requests captions"| node_visual
node_indexer -->|"writes vectors"| node_qdrant
node_indexer -->|"records document state"| node_db
node_search_api -->|"retrieves passages"| node_retrieval
node_chat_api -->|"runs conversation"| node_agent
node_agent -->|"requests context"| node_retrieval
node_agent -->|"routes and generates"| node_llm
node_retrieval -.->|"embeds and reranks"| node_embeddings
node_retrieval -.->|"queries page vectors"| node_visual_search
node_retrieval -->|"searches vectors"| node_qdrant
node_agent -->|"checkpoints state"| node_db
node_worker -->|"scores queued answers"| node_evaluation
node_evaluation -->|"judges answers"| node_llm
node_backend -->|"sets up tracing"| node_tracing
node_worker -->|"sets up tracing"| node_tracing
node_tracing -.->|"exports traces"| node_phoenix

click node_ui "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/App.tsx"
click node_ui_chat "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/Chat.tsx"
click node_ui_admin "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/Admin.tsx"
click node_api_client "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/api.ts"
click node_backend "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/main.py"
click node_auth "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/auth.py"
click node_document_api "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/documents.py"
click node_search_api "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/search.py"
click node_chat_api "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/chat.py"
click node_admin_api "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/admin.py"
click node_worker "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/worker/main.py"
click node_queue "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/queue.py"
click node_indexer "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/indexer.py"
click node_pipeline "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/pipeline.py"
click node_file_storage "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/storage.py"
click node_visual "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/vlm/main.py"
click node_db "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/db/session.py"
click node_retrieval "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/retrieval/retriever.py"
click node_agent "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/graph/runtime.py"
click node_llm "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/llm/client.py"
click node_embeddings "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/embeddings/main.py"
click node_visual_search "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/colqwen/main.py"
click node_qdrant "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/qdrant_index.py"
click node_evaluation "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/eval/runner.py"
click node_tracing "https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/observability/tracing.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_ui,node_ui_chat,node_ui_admin,node_api_client toneBlue
class node_backend,node_auth,node_document_api,node_search_api,node_chat_api,node_admin_api toneAmber
class node_worker,node_queue,node_indexer,node_pipeline,node_file_storage,node_visual,node_db toneMint
class node_retrieval,node_agent,node_llm,node_embeddings,node_visual_search,node_qdrant toneRose
class node_evaluation,node_tracing,node_user,node_admin,node_phoenix toneIndigo
```

## Components

### User experience

- [Admin and chat UI](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/App.tsx): `admin-ui/app/src/App.tsx`
- [Chat interface](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/Chat.tsx): `admin-ui/app/src/Chat.tsx`
- [Admin interface](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/Admin.tsx): `admin-ui/app/src/Admin.tsx`
- [UI API client](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/admin-ui/app/src/api.ts): `admin-ui/app/src/api.ts`

### Backend API

- [FastAPI application](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/main.py): `app/main.py`
- [Authentication and access control](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/auth.py): `app/api/auth.py`
- [Document endpoints](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/documents.py): `app/api/documents.py`
- [Search endpoints](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/search.py): `app/api/search.py`
- [Chat endpoints](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/chat.py): `app/api/chat.py`
- [Admin endpoints](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/api/admin.py): `app/api/admin.py`

### Knowledge pipeline

- [Background worker](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/worker/main.py): `worker/main.py`
- [Redis job queues](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/queue.py): `app/queue.py`
- [Document indexer](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/indexer.py): `app/ingestion/indexer.py`
- [Parse and chunk](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [Uploaded-file storage](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/storage.py): `app/ingestion/storage.py`
- [Visual document services](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/vlm/main.py): `services/vlm/main.py`
- [PostgreSQL](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/db/session.py): `app/db/session.py`

### Retrieval and answers

- [Hybrid retrieval](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/retrieval/retriever.py): `app/retrieval/retriever.py`
- [Agent graph](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/graph/runtime.py): `app/graph/runtime.py`
- [LLM client](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/llm/client.py): `app/llm/client.py`
- [Embedding and reranking service](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/embeddings/main.py): `services/embeddings/main.py`
- [Visual retrieval service](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/services/colqwen/main.py): `services/colqwen/main.py`
- [Qdrant vector store](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/ingestion/qdrant_index.py): `app/ingestion/qdrant_index.py`

### Operations and evaluation

- [Evaluation and judging](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/eval/runner.py): `app/eval/runner.py`
- [Tracing and metrics](https://github.com/lkmbh42/agentic_rag_claudecode/blob/feat/multimodal-migration/app/observability/tracing.py): `app/observability/tracing.py`

### Other components

- **Employee**
- **Administrator**
- **Phoenix**

## Connections

- Employee → Admin and chat UI: uses
- Administrator → Admin and chat UI: uses
- Admin and chat UI → UI API client: calls
- UI API client → FastAPI application: sends requests
- Admin and chat UI → Chat interface: shows
- Admin and chat UI → Admin interface: shows
- FastAPI application → Authentication and access control: dispatches
- FastAPI application → Document endpoints: dispatches
- FastAPI application → Search endpoints: dispatches
- FastAPI application → Chat endpoints: dispatches
- FastAPI application → Admin endpoints: dispatches
- Document endpoints → Uploaded-file storage: stores uploads
- Document endpoints → Redis job queues: enqueues indexing
- Background worker → Redis job queues: consumes jobs
- Background worker → Document indexer: indexes documents
- Document indexer → Uploaded-file storage: reads uploads
- Document indexer → Parse and chunk: parses and chunks
- Parse and chunk → Visual document services: requests captions
- Document indexer → Qdrant vector store: writes vectors
- Document indexer → PostgreSQL: records document state
- Search endpoints → Hybrid retrieval: retrieves passages
- Chat endpoints → Agent graph: runs conversation
- Agent graph → Hybrid retrieval: requests context
- Agent graph → LLM client: routes and generates
- Hybrid retrieval → Embedding and reranking service: embeds and reranks
- Hybrid retrieval → Visual retrieval service: queries page vectors
- Hybrid retrieval → Qdrant vector store: searches vectors
- Agent graph → PostgreSQL: checkpoints state
- Background worker → Evaluation and judging: scores queued answers
- Evaluation and judging → LLM client: judges answers
- FastAPI application → Tracing and metrics: sets up tracing
- Background worker → Tracing and metrics: sets up tracing
- Tracing and metrics → Phoenix: exports traces