How mazleon/chatbot-rag-ray works
1. Overall shape
This repo is a two-tier system: a React/TypeScript frontend in frontend/ and a FastAPI backend in app/ exposed under /api/v1. The backend is the main orchestration layer; it does not just proxy requests, it runs the agent workflow, session memory, document retrieval, and LLM calls.
2. Frontend boundary
The frontend is a Vite app with a chat-oriented UI built from ChatWindow, ChatInput, MessageBubble, and Sidebar. ChatContext holds conversation state on the client, while frontend/src/services/api.ts is the only network boundary to the backend. The UI is responsible for user interaction and rendering, not for business logic or retrieval.
3. API layer
app/api/router.py and app/api/routes.py define the external contract: health, chat, document upload, session history, and session deletion. This is the system boundary where frontend requests enter the backend. app/models/schemas.py defines the request/response shapes that stabilize that contract.
4. Agent orchestration
The core brain lives in app/agents/graph.py, which is a LangGraph-based workflow. The agent likely routes a message through intent classification, retrieval, and generation steps rather than using a single monolithic prompt. This makes the backend a stateful decision pipeline instead of a simple LLM wrapper.
5. Retrieval-Augmented Generation path
app/services/rag.py is the retrieval subsystem. It connects the agent to a FAISS vector store built from the knowledge base and uploaded documents. The RAG path is used when a user question needs factual grounding in insurance content, especially for uploaded files and the seed knowledge corpus in data/raw_docs/insurance_knowledge.json.
6. Document ingestion and parsing
There are two ingestion paths: a scripted offline path via scripts/ingest.py, and an online upload path through the API. app/services/parser.py handles extracting usable text from uploaded content, while the backend turns that text into embeddings and stores it in the vector index. This is the bridge between user-provided documents and retrieval.
7. Session memory
Conversational context is isolated in app/memory/manager.py. The readme indicates this memory is backed by Redis, so session state is externalized from the API process and survives across requests/instances. The agent uses this layer for history, user name recall, and conversation summarization.
8. LLM and observability
app/services/llm.py abstracts the model provider, with configuration supporting OpenAI-style providers and model selection from environment variables. app/services/langfuse.py adds optional tracing/telemetry for prompts and generations. So the generation path is: agent → LLM service → external LLM API, with optional LangFuse tracing alongside it.
9. Backend cross-cutting concerns
app/core/config.py, constants.py, and logging.py centralize runtime configuration, environment-driven behavior, and logs. app/utils/exceptions.py provides a controlled error boundary. These modules don’t implement features directly, but they shape deployment behavior and the API’s failure modes.
10. Deployment topology
The repo is container-first: Dockerfile, frontend/Dockerfile, docker-compose.yml, .env.docker, and nginx.conf define the runtime stack. The compose setup runs the backend, frontend, and Redis together, with the backend waiting on health checks. This is the main production/development topology, not just a local dev convenience.
11. Data and knowledge assets
data/raw_docs/ contains the seeded insurance corpus used by the RAG system. Uploaded documents extend that knowledge base at runtime, but the repo also ships with prebuilt domain content for immediate usefulness. The vector store itself is treated as derived state, not source code.
12. Quality and delivery
The backend has unit and integration tests under tests/, and the frontend has Vitest coverage under frontend/src/test/. GitHub Actions workflows cover CI, deploy, and security checks, so the repository has a clear separation between application runtime, validation, and release automation.
13. Key data flows to diagram
The main flow is: user message in React → POST to FastAPI chat endpoint → LangGraph agent → Redis memory + RAG retrieval from FAISS + LLM call → response back to frontend. A secondary flow is: document upload or offline ingestion → parser → embeddings/vector store → later retrieval by the agent. Those are the two critical paths for an architecture diagram.
Main entry points: routes.py API routes · docker-compose.yml Compose stack · graph.py Agent graph · App.tsx App shell
Components 22
Frontend
React/Vite chat UI and client-side state
- App shell · Top-level client application and UI composition
frontend/src/App.tsx - Chat state · Conversation state and UI coordination on the client
frontend/src/context/ChatContext.tsx - Chat window · Main conversation viewport for messages and responses
frontend/src/components/ChatWindow.tsx - Chat input · Message entry and submit control
frontend/src/components/ChatInput.tsx - API client · Only frontend boundary for backend requests
frontend/src/services/api.ts
Backend
FastAPI API, agent workflow, and supporting services
- API router · External HTTP contract and route wiring
app/api/router.py - API routes · Health, chat, upload, and session endpoints
app/api/routes.py - Schemas · Request and response shapes for the API contract
app/models/schemas.py - Agent graph · Stateful orchestration of intent, retrieval, and generation
app/agents/graph.py - RAG service · Grounding over FAISS-backed knowledge and uploads
app/services/rag.py - Parser · Extracts usable text from uploaded documents
app/services/parser.py - Memory · Conversation history and session persistence, backed by Redis
app/memory/manager.py - LLM service · Provider abstraction for chat generation
app/services/llm.py
Platform
Deployment, runtime, and observability concerns
- Tracing · Optional prompt and generation tracing
app/services/langfuse.py - Config · Environment-driven settings and application behavior
app/core/config.py - Errors · Controlled exception handling and API failure shaping
app/utils/exceptions.py - Compose stack · Containerized backend, frontend, and Redis runtime
docker-compose.yml - Frontend image · Build recipe for the client runtime
frontend/Dockerfile - Backend image · Build recipe for the API runtime
Dockerfile - Nginx · Edge proxy for serving and routing traffic
nginx.conf
Data
Seed corpus and ingestion pipeline
- Seed corpus · Bundled insurance content used for retrieval grounding
data/raw_docs/insurance_knowledge.json - Ingest · Offline document ingestion into the retrieval index
scripts/ingest.py
Connections 25
- App shell → Chat state: uses state · App shell consumes conversation state
- App shell → Chat window: renders · App composes the main chat viewport
- App shell → Chat input: renders · App composes the message entry controls
- Chat window → Chat state: reads · Message list and UI state come from context
- Chat input → Chat state: updates · Submitting a message updates client state
- Chat input → API client: sends · User messages are sent through the API client
- API client → API router: calls · Network boundary from frontend to backend
- API router → API routes: mounts · Router aggregates the public endpoints
- API routes → Schemas: validates · Endpoints use request and response models
- API routes → Agent graph: invokes · Chat requests enter the orchestration workflow
- API routes → Parser: uploads · Upload path extracts text from documents
- API routes → Memory: reads/writes · Session history is persisted externally
- Agent graph → Memory: remembers · Agent uses session memory for context
- Agent graph → RAG service: retrieves · Agent grounds answers with document retrieval
- Agent graph → LLM service: generates · Agent delegates response generation to the model adapter
- RAG service → Seed corpus: indexes · Seed domain knowledge is part of retrieval material
- Ingest → Parser: parses · Offline ingestion uses the same parsing logic
- Ingest → RAG service: builds index · Ingested text becomes retrievable embeddings
- LLM service → Config: reads · Model provider and runtime settings come from config
- Tracing → LLM service: traces · Tracing wraps or observes model calls
- API routes → Errors: handles · API errors are normalized at the boundary
- Compose stack → Backend image: builds · Compose orchestrates the backend image
- Compose stack → Frontend image: builds · Compose orchestrates the frontend image
- Compose stack → Nginx: routes through · Container stack includes edge routing
- Compose stack → Memory: depends on · Redis-backed session state is part of the runtime stack