# mazleon/chatbot-rag-ray architecture

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

- Interactive diagram: https://gitdiagram.com/mazleon/chatbot-rag-ray
- Repository: https://github.com/mazleon/chatbot-rag-ray

## Overview

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: [`app/api/routes.py`](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/api/routes.py) (API routes), [`docker-compose.yml`](https://github.com/mazleon/chatbot-rag-ray/blob/main/docker-compose.yml) (Compose stack), [`app/agents/graph.py`](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/agents/graph.py) (Agent graph), [`frontend/src/App.tsx`](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React app<br/>[App.tsx]"]
  node_frontend_chat_context(("Chat state<br/>client state<br/>[ChatContext.tsx]"))
  node_frontend_chat_window["Chat window<br/>ui component<br/>[ChatWindow.tsx]"]
  node_frontend_chat_input["Chat input<br/>ui component<br/>[ChatInput.tsx]"]
  node_frontend_api["API client<br/>network adapter<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_api_router["API router<br/>[router.py]"]
  node_api_routes["API routes<br/>FastAPI endpoints<br/>[routes.py]"]
  node_schemas["Schemas<br/>Pydantic models<br/>[schemas.py]"]
  node_agent_graph{{"Agent graph<br/>LangGraph workflow<br/>[graph.py]"}}
  node_rag_service[("RAG service<br/>retrieval layer<br/>[rag.py]")]
  node_parser_service["Parser<br/>[parser.py]"]
  node_memory_manager[("Memory<br/>session store<br/>[manager.py]")]
  node_llm_service["LLM service<br/>model adapter<br/>[llm.py]"]
end

subgraph group_platform["Platform"]
  node_langfuse_service["Tracing<br/>telemetry<br/>[langfuse.py]"]
  node_config["Config<br/>[config.py]"]
  node_exceptions["Errors<br/>error boundary<br/>[exceptions.py]"]
  node_compose_stack["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_frontend_docker["Frontend image<br/>container build"]
  node_backend_docker["Backend image<br/>container build"]
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
end

subgraph group_data["Data"]
  node_seed_corpus["Seed corpus<br/>knowledge base"]
  node_ingest_script["Ingest<br/>pipeline script<br/>[ingest.py]"]
end

node_frontend_app -->|"uses state"| node_frontend_chat_context
node_frontend_app -->|"renders"| node_frontend_chat_window
node_frontend_app -->|"renders"| node_frontend_chat_input
node_frontend_chat_window -->|"reads"| node_frontend_chat_context
node_frontend_chat_input -->|"updates"| node_frontend_chat_context
node_frontend_chat_input -->|"sends"| node_frontend_api
node_frontend_api -->|"calls"| node_api_router
node_api_router -->|"mounts"| node_api_routes
node_api_routes -->|"validates"| node_schemas
node_api_routes -->|"invokes"| node_agent_graph
node_api_routes -->|"uploads"| node_parser_service
node_api_routes -->|"reads/writes"| node_memory_manager
node_agent_graph -->|"remembers"| node_memory_manager
node_agent_graph -->|"retrieves"| node_rag_service
node_agent_graph -->|"generates"| node_llm_service
node_rag_service -->|"indexes"| node_seed_corpus
node_ingest_script -->|"parses"| node_parser_service
node_ingest_script -->|"builds index"| node_rag_service
node_llm_service -->|"reads"| node_config
node_langfuse_service -.->|"traces"| node_llm_service
node_api_routes -->|"handles"| node_exceptions
node_compose_stack -->|"builds"| node_backend_docker
node_compose_stack -->|"builds"| node_frontend_docker
node_compose_stack -->|"routes through"| node_nginx
node_compose_stack -->|"depends on"| node_memory_manager

click node_frontend_app "https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/App.tsx"
click node_frontend_chat_context "https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/context/ChatContext.tsx"
click node_frontend_chat_window "https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/components/ChatWindow.tsx"
click node_frontend_chat_input "https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/components/ChatInput.tsx"
click node_frontend_api "https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/services/api.ts"
click node_api_router "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/api/router.py"
click node_api_routes "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/api/routes.py"
click node_schemas "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/models/schemas.py"
click node_agent_graph "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/agents/graph.py"
click node_rag_service "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/rag.py"
click node_parser_service "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/parser.py"
click node_memory_manager "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/memory/manager.py"
click node_llm_service "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/llm.py"
click node_langfuse_service "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/langfuse.py"
click node_config "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/core/config.py"
click node_exceptions "https://github.com/mazleon/chatbot-rag-ray/blob/main/app/utils/exceptions.py"
click node_seed_corpus "https://github.com/mazleon/chatbot-rag-ray/blob/main/data/raw_docs/insurance_knowledge.json"
click node_ingest_script "https://github.com/mazleon/chatbot-rag-ray/blob/main/scripts/ingest.py"
click node_compose_stack "https://github.com/mazleon/chatbot-rag-ray/blob/main/docker-compose.yml"
click node_frontend_docker "https://github.com/mazleon/chatbot-rag-ray/tree/main/frontend/Dockerfile"
click node_backend_docker "https://github.com/mazleon/chatbot-rag-ray/tree/main/Dockerfile"
click node_nginx "https://github.com/mazleon/chatbot-rag-ray/blob/main/nginx.conf"

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_frontend_app,node_frontend_chat_context,node_frontend_chat_window,node_frontend_chat_input,node_frontend_api toneBlue
class node_api_router,node_api_routes,node_schemas,node_agent_graph,node_rag_service,node_parser_service,node_memory_manager,node_llm_service toneAmber
class node_langfuse_service,node_config,node_exceptions,node_compose_stack,node_frontend_docker,node_backend_docker,node_nginx toneMint
class node_seed_corpus,node_ingest_script toneRose
```

## Components

### Frontend

React/Vite chat UI and client-side state

- [App shell](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/App.tsx): React app · Top-level client application and UI composition · `frontend/src/App.tsx`
- [Chat state](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/context/ChatContext.tsx): client state · Conversation state and UI coordination on the client · `frontend/src/context/ChatContext.tsx`
- [Chat window](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/components/ChatWindow.tsx): ui component · Main conversation viewport for messages and responses · `frontend/src/components/ChatWindow.tsx`
- [Chat input](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/components/ChatInput.tsx): ui component · Message entry and submit control · `frontend/src/components/ChatInput.tsx`
- [API client](https://github.com/mazleon/chatbot-rag-ray/blob/main/frontend/src/services/api.ts): network adapter · Only frontend boundary for backend requests · `frontend/src/services/api.ts`

### Backend

FastAPI API, agent workflow, and supporting services

- [API router](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/api/router.py): FastAPI router · External HTTP contract and route wiring · `app/api/router.py`
- [API routes](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/api/routes.py): FastAPI endpoints · Health, chat, upload, and session endpoints · `app/api/routes.py`
- [Schemas](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/models/schemas.py): Pydantic models · Request and response shapes for the API contract · `app/models/schemas.py`
- [Agent graph](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/agents/graph.py): LangGraph workflow · Stateful orchestration of intent, retrieval, and generation · `app/agents/graph.py`
- [RAG service](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/rag.py): retrieval layer · Grounding over FAISS-backed knowledge and uploads · `app/services/rag.py`
- [Parser](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/parser.py): document parser · Extracts usable text from uploaded documents · `app/services/parser.py`
- [Memory](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/memory/manager.py): session store · Conversation history and session persistence, backed by Redis · `app/memory/manager.py`
- [LLM service](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/llm.py): model adapter · Provider abstraction for chat generation · `app/services/llm.py`

### Platform

Deployment, runtime, and observability concerns

- [Tracing](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/services/langfuse.py): telemetry · Optional prompt and generation tracing · `app/services/langfuse.py`
- [Config](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/core/config.py): runtime config · Environment-driven settings and application behavior · `app/core/config.py`
- [Errors](https://github.com/mazleon/chatbot-rag-ray/blob/main/app/utils/exceptions.py): error boundary · Controlled exception handling and API failure shaping · `app/utils/exceptions.py`
- [Compose stack](https://github.com/mazleon/chatbot-rag-ray/blob/main/docker-compose.yml): deployment · Containerized backend, frontend, and Redis runtime · `docker-compose.yml`
- [Frontend image](https://github.com/mazleon/chatbot-rag-ray/tree/main/frontend/Dockerfile): container build · Build recipe for the client runtime · `frontend/Dockerfile`
- [Backend image](https://github.com/mazleon/chatbot-rag-ray/tree/main/Dockerfile): container build · Build recipe for the API runtime · `Dockerfile`
- [Nginx](https://github.com/mazleon/chatbot-rag-ray/blob/main/nginx.conf): reverse proxy · Edge proxy for serving and routing traffic · `nginx.conf`

### Data

Seed corpus and ingestion pipeline

- [Seed corpus](https://github.com/mazleon/chatbot-rag-ray/blob/main/data/raw_docs/insurance_knowledge.json): knowledge base · Bundled insurance content used for retrieval grounding · `data/raw_docs/insurance_knowledge.json`
- [Ingest](https://github.com/mazleon/chatbot-rag-ray/blob/main/scripts/ingest.py): pipeline script · Offline document ingestion into the retrieval index · `scripts/ingest.py`

## Connections

- 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
