# zhanghang2017/ai-chat-rag architecture

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

- Interactive diagram: https://gitdiagram.com/zhanghang2017/ai-chat-rag
- Repository: https://github.com/zhanghang2017/ai-chat-rag

## Overview

AI-CHAT-RAG is a local knowledge-base RAG application: users upload and manage files, which are indexed into a vector store, then ask questions answered with retrieved context. The graph separates the React client, Node business service and Python AI service, showing documented ingestion callbacks and chat streaming. README documents the major workflows; sampled source confirms selected ingestion, callback and chat entry points, so some internal wiring is shown only where supported.

Main entry points: [`backend-server/src/services/file.service.ts`](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/file.service.ts) (File operations), [`AI-server/app/knowledge_base/ingestion_service.py`](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/ingestion_service.py) (Document ingestion), [`backend-server/src/controllers/chat.controller.ts`](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/chat.controller.ts) (Chat API), [`backend-server/src/controllers/file.controller.ts`](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/file.controller.ts) (File API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_app["App and pages<br/>[App.tsx]"]
  node_kb_hook["Knowledge-base actions"]
  node_upload_work["Upload workflow"]
  node_ingestion_events["Ingestion events"]
  node_chat_ui["Chat interface<br/>[ChatPage.tsx]"]
  node_chat_work["Chat client<br/>[chatWorkservice.ts]"]
end

subgraph group_backend["Node business service"]
  node_file_controller["File API<br/>[file.controller.ts]"]
  node_file_service["File operations<br/>[file.service.ts]"]
  node_ingestion_scheduler["Ingestion scheduling"]
  node_event_service["Ingestion events<br/>[ingestionEvents.ts]"]
  node_file_repo["File records<br/>[file.repository.ts]"]
  node_task_repo["Task records<br/>[task.repository.ts]"]
  node_chat_controller["Chat API<br/>[chat.controller.ts]"]
  node_chat_service["Chat sessions<br/>[chat.service.ts]"]
  node_chat_repo["Chat records<br/>[chat.repository.ts]"]
  node_ai_proxy["AI service proxy<br/>[ai.service.ts]"]
end

subgraph group_ai["Python AI service"]
  node_ai_entry["AI API<br/>[main.py]"]
  node_ingestion["Document ingestion"]
  node_doc_loader["Document parsing<br/>[document_loader.py]"]
  node_embedding["Embedding model<br/>[embedding_model.py]"]
  node_vector_store["Vector store access<br/>[vector_store.py]"]
  node_callback["Ingestion callbacks"]
  node_chat_ai["RAG chat<br/>[service.py]"]
  node_retriever["Knowledge retrieval<br/>[retriever.py]"]
  node_llm["Chat model<br/>[llm.py]"]
end

subgraph group_integrations["State and AI integrations"]
  node_database[("Application database<br/>[prisma.ts]")]
  node_chroma[("Chroma vector store")]
  node_embedding_service{{"Embedding provider"}}
  node_chat_model{{"Chat model provider"}}
end

node_user(("User"))

node_user -->|"uses"| node_client_app
node_client_app -->|"opens knowledge base"| node_kb_hook
node_kb_hook -->|"uploads and manages"| node_upload_work
node_upload_work -->|"sends file requests"| node_file_controller
node_file_controller -->|"delegates"| node_file_service
node_file_service -->|"reads and writes"| node_file_repo
node_file_service -->|"reads and writes"| node_task_repo
node_file_service -->|"schedules tasks"| node_ingestion_scheduler
node_file_service -->|"dispatches ingestion"| node_ai_entry
node_ai_entry -->|"queues background job"| node_ingestion
node_ingestion -->|"parses documents"| node_doc_loader
node_ingestion -->|"vectorizes chunks"| node_embedding
node_embedding -.->|"requests embeddings"| node_embedding_service
node_ingestion -->|"writes chunks"| node_vector_store
node_vector_store -->|"reads and writes vectors"| node_chroma
node_ingestion -->|"reports progress and chunks"| node_callback
node_callback -->|"posts callbacks"| node_file_controller
node_file_controller -->|"handles callback data"| node_file_service
node_file_service -->|"publishes status events"| node_event_service
node_ingestion_events -->|"receives event stream"| node_event_service
node_kb_hook -->|"refreshes on updates"| node_ingestion_events
node_client_app -->|"opens chat"| node_chat_ui
node_chat_ui -->|"submits questions"| node_chat_work
node_chat_work -->|"sends chat requests"| node_chat_controller
node_chat_controller -->|"manages sessions and messages"| node_chat_service
node_chat_service -->|"reads and writes"| node_chat_repo
node_chat_controller -->|"requests streamed answer"| node_ai_proxy
node_ai_proxy -->|"forwards chat request"| node_ai_entry
node_ai_entry -->|"starts stream"| node_chat_ai
node_chat_ai -->|"retrieves context"| node_retriever
node_retriever -->|"searches vectors"| node_vector_store
node_chat_ai -->|"generates response"| node_llm
node_llm -.->|"requests completion"| node_chat_model
node_chat_controller -->|"streams answer events"| node_chat_work
node_file_repo -->|"persists file metadata"| node_database
node_task_repo -->|"persists task state"| node_database
node_chat_repo -->|"persists chat history"| node_database

click node_client_app "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/App.tsx"
click node_kb_hook "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/hooks/useKnowledgeBasePage.ts"
click node_upload_work "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/workservice/uploadWorkservice.ts"
click node_ingestion_events "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/components/knowledge-base/IngestionEventProvider.tsx"
click node_chat_ui "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/routes/ChatPage.tsx"
click node_chat_work "https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/workservice/chatWorkservice.ts"
click node_file_controller "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/file.controller.ts"
click node_file_service "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/file.service.ts"
click node_ingestion_scheduler "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ingestionScheduler.ts"
click node_event_service "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ingestionEvents.ts"
click node_file_repo "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/file.repository.ts"
click node_task_repo "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/task.repository.ts"
click node_chat_controller "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/chat.controller.ts"
click node_chat_service "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/chat.service.ts"
click node_chat_repo "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/chat.repository.ts"
click node_ai_proxy "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ai.service.ts"
click node_ai_entry "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/main.py"
click node_ingestion "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/ingestion_service.py"
click node_doc_loader "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/document_loader.py"
click node_embedding "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/embedding_model.py"
click node_vector_store "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/vector_store.py"
click node_callback "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/ingestion_callback_client.py"
click node_chat_ai "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/service.py"
click node_retriever "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/retriever.py"
click node_llm "https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/llm.py"
click node_database "https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/lib/prisma.ts"

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_client_app,node_kb_hook,node_upload_work,node_ingestion_events,node_chat_ui,node_chat_work,node_user toneBlue
class node_file_controller,node_file_service,node_ingestion_scheduler,node_event_service,node_file_repo,node_task_repo,node_chat_controller,node_chat_service,node_chat_repo,node_ai_proxy toneAmber
class node_ai_entry,node_ingestion,node_doc_loader,node_embedding,node_vector_store,node_callback,node_chat_ai,node_retriever,node_llm toneMint
class node_database,node_chroma,node_embedding_service,node_chat_model toneRose
```

## Components

### React client

- [App and pages](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Knowledge-base actions](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/hooks/useKnowledgeBasePage.ts): `client/src/hooks/useKnowledgeBasePage.ts`
- [Upload workflow](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/workservice/uploadWorkservice.ts): `client/src/workservice/uploadWorkservice.ts`
- [Ingestion events](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/components/knowledge-base/IngestionEventProvider.tsx): `client/src/components/knowledge-base/IngestionEventProvider.tsx`
- [Chat interface](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/routes/ChatPage.tsx): `client/src/routes/ChatPage.tsx`
- [Chat client](https://github.com/zhanghang2017/ai-chat-rag/blob/main/client/src/workservice/chatWorkservice.ts): `client/src/workservice/chatWorkservice.ts`

### Node business service

- [File API](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/file.controller.ts): `backend-server/src/controllers/file.controller.ts`
- [File operations](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/file.service.ts): `backend-server/src/services/file.service.ts`
- [Ingestion scheduling](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ingestionScheduler.ts): `backend-server/src/services/ingestionScheduler.ts`
- [Ingestion events](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ingestionEvents.ts): `backend-server/src/services/ingestionEvents.ts`
- [File records](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/file.repository.ts): `backend-server/src/repositories/file.repository.ts`
- [Task records](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/task.repository.ts): `backend-server/src/repositories/task.repository.ts`
- [Chat API](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/controllers/chat.controller.ts): `backend-server/src/controllers/chat.controller.ts`
- [Chat sessions](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/chat.service.ts): `backend-server/src/services/chat.service.ts`
- [Chat records](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/repositories/chat.repository.ts): `backend-server/src/repositories/chat.repository.ts`
- [AI service proxy](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/services/ai.service.ts): `backend-server/src/services/ai.service.ts`

### Python AI service

- [AI API](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/main.py): `AI-server/main.py`
- [Document ingestion](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/ingestion_service.py): `AI-server/app/knowledge_base/ingestion_service.py`
- [Document parsing](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/document_loader.py): `AI-server/app/knowledge_base/document_loader.py`
- [Embedding model](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/embedding_model.py): `AI-server/app/knowledge_base/embedding_model.py`
- [Vector store access](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/vector_store.py): `AI-server/app/knowledge_base/vector_store.py`
- [Ingestion callbacks](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/knowledge_base/ingestion_callback_client.py): `AI-server/app/knowledge_base/ingestion_callback_client.py`
- [RAG chat](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/service.py): `AI-server/app/chat/service.py`
- [Knowledge retrieval](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/retriever.py): `AI-server/app/chat/retriever.py`
- [Chat model](https://github.com/zhanghang2017/ai-chat-rag/blob/main/AI-server/app/chat/llm.py): `AI-server/app/chat/llm.py`

### State and AI integrations

- [Application database](https://github.com/zhanghang2017/ai-chat-rag/blob/main/backend-server/src/lib/prisma.ts): `backend-server/src/lib/prisma.ts`
- **Chroma vector store**
- **Embedding provider**
- **Chat model provider**

### Other components

- **User**

## Connections

- User → App and pages: uses
- App and pages → Knowledge-base actions: opens knowledge base
- Knowledge-base actions → Upload workflow: uploads and manages
- Upload workflow → File API: sends file requests
- File API → File operations: delegates
- File operations → File records: reads and writes
- File operations → Task records: reads and writes
- File operations → Ingestion scheduling: schedules tasks
- File operations → AI API: dispatches ingestion
- AI API → Document ingestion: queues background job
- Document ingestion → Document parsing: parses documents
- Document ingestion → Embedding model: vectorizes chunks
- Embedding model → Embedding provider: requests embeddings
- Document ingestion → Vector store access: writes chunks
- Vector store access → Chroma vector store: reads and writes vectors
- Document ingestion → Ingestion callbacks: reports progress and chunks
- Ingestion callbacks → File API: posts callbacks
- File API → File operations: handles callback data
- File operations → Ingestion events: publishes status events
- Ingestion events → Ingestion events: receives event stream
- Knowledge-base actions → Ingestion events: refreshes on updates
- App and pages → Chat interface: opens chat
- Chat interface → Chat client: submits questions
- Chat client → Chat API: sends chat requests
- Chat API → Chat sessions: manages sessions and messages
- Chat sessions → Chat records: reads and writes
- Chat API → AI service proxy: requests streamed answer
- AI service proxy → AI API: forwards chat request
- AI API → RAG chat: starts stream
- RAG chat → Knowledge retrieval: retrieves context
- Knowledge retrieval → Vector store access: searches vectors
- RAG chat → Chat model: generates response
- Chat model → Chat model provider: requests completion
- Chat API → Chat client: streams answer events
- File records → Application database: persists file metadata
- Task records → Application database: persists task state
- Chat records → Application database: persists chat history