# theborulesai/agentic-rag-assistant architecture

> Architecture diagram of the GitHub repository theborulesai/agentic-rag-assistant, 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/theborulesai/agentic-rag-assistant
- Repository: https://github.com/theborulesai/agentic-rag-assistant

## Overview

This is an agentic RAG assistant: users ask questions in a React chat, and a LangGraph agent can retrieve indexed documents, search the live web, then stream a cited answer and activity events back to the UI. Documents enter through upload or first-boot sample seeding, then are split, embedded, and persisted for retrieval. The README also documents LangSmith tracing and an offline evaluation suite. Several backend modules and evaluation implementations were not sampled; their nodes and connections rely on README claims and the repository tree.

Main entry points: [`src/rag_agent/streaming.py`](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/streaming.py) (Stream bridge), [`frontend/src/hooks/useAgentStream.ts`](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/hooks/useAgentStream.ts) (Stream state), [`src/rag_agent/agent.py`](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/agent.py) (ReAct agent), [`src/rag_agent/api.py`](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/api.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_web_ui["Chat UI<br/>[App.tsx]"]
  node_stream_hook["Stream state<br/>[useAgentStream.ts]"]
  node_sse_parser["SSE parser<br/>[sse.ts]"]
  node_upload_ui["Document upload<br/>[UploadDialog.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_orchestration["Agent and API"]
  node_api["FastAPI<br/>[api.py]"]
  node_streaming["Stream bridge<br/>[streaming.py]"]
  node_agent["ReAct agent<br/>[agent.py]"]
  node_schemas["Event schemas<br/>[schemas.py]"]
  node_thread_memory[("Thread memory<br/>[agent.py]")]
end

subgraph group_knowledge["Knowledge and tools"]
  node_ingest["Ingestion<br/>[ingest.py]"]
  node_embedding_factory["Embeddings<br/>[embeddings.py]"]
  node_vectorstore["Vector store access<br/>[vectorstore.py]"]
  node_chroma[("Chroma index<br/>[vectorstore.py]")]
  node_tools["Agent tools<br/>[tools.py]"]
  node_llms["Model factories<br/>[llms.py]"]
  node_sample_docs["Sample documents"]
end

subgraph group_observability["Tracing and evaluation"]
  node_langsmith{{"LangSmith"}}
  node_evaluations["Evaluation suite<br/>[run_evals.py]"]
end

node_user(("User"))
node_openai{{"OpenAI models"}}
node_web_search{{"Web search"}}

node_user -->|"asks"| node_web_ui
node_web_ui -->|"submits"| node_stream_hook
node_stream_hook -->|"POST chat"| node_api
node_api -->|"streams events"| node_streaming
node_streaming -->|"consumes astream"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"uses models"| node_llms
node_llms -->|"calls"| node_openai
node_tools -->|"retrieves documents"| node_vectorstore
node_vectorstore -->|"reads and writes"| node_chroma
node_tools -->|"searches web"| node_web_search
node_agent -->|"checkpoints threads"| node_thread_memory
node_streaming -->|"formats events"| node_schemas
node_streaming -.->|"auto-traces"| node_langsmith
node_streaming -->|"SSE events"| node_stream_hook
node_stream_hook -->|"parses stream"| node_sse_parser
node_sse_parser -->|"yields events"| node_stream_hook
node_web_ui -->|"offers upload"| node_upload_ui
node_upload_ui -->|"uploads files"| node_api_client
node_api_client -->|"POST ingest"| node_api
node_api -->|"ingests files"| node_ingest
node_sample_docs -->|"seeded on boot"| node_ingest
node_ingest -->|"embeds chunks"| node_embedding_factory
node_embedding_factory -->|"requests embeddings"| node_openai
node_ingest -->|"persists chunks"| node_vectorstore
node_evaluations -.->|"runs evaluations"| node_langsmith

click node_web_ui "https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/App.tsx"
click node_stream_hook "https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/hooks/useAgentStream.ts"
click node_sse_parser "https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/lib/sse.ts"
click node_upload_ui "https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/components/upload/UploadDialog.tsx"
click node_api_client "https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/api.py"
click node_streaming "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/streaming.py"
click node_agent "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/agent.py"
click node_schemas "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/schemas.py"
click node_ingest "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/ingest.py"
click node_embedding_factory "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/embeddings.py"
click node_vectorstore "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/vectorstore.py"
click node_chroma "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/vectorstore.py"
click node_tools "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/tools.py"
click node_llms "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/llms.py"
click node_sample_docs "https://github.com/theborulesai/agentic-rag-assistant/tree/main/data/sample_docs"
click node_thread_memory "https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/agent.py"
click node_evaluations "https://github.com/theborulesai/agentic-rag-assistant/blob/main/evals/run_evals.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_web_ui,node_stream_hook,node_sse_parser,node_upload_ui,node_api_client,node_user toneBlue
class node_api,node_streaming,node_agent,node_schemas,node_thread_memory toneAmber
class node_ingest,node_embedding_factory,node_vectorstore,node_chroma,node_tools,node_llms,node_sample_docs toneMint
class node_langsmith,node_evaluations toneRose
class node_openai,node_web_search toneIndigo
```

## Components

### Chat experience

- [Chat UI](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Stream state](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/hooks/useAgentStream.ts): `frontend/src/hooks/useAgentStream.ts`
- [SSE parser](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/lib/sse.ts): `frontend/src/lib/sse.ts`
- [Document upload](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/components/upload/UploadDialog.tsx): `frontend/src/components/upload/UploadDialog.tsx`
- [API client](https://github.com/theborulesai/agentic-rag-assistant/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Agent and API

- [FastAPI](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/api.py): `src/rag_agent/api.py`
- [Stream bridge](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/streaming.py): `src/rag_agent/streaming.py`
- [ReAct agent](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/agent.py): `src/rag_agent/agent.py`
- [Event schemas](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/schemas.py): `src/rag_agent/schemas.py`
- [Thread memory](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/agent.py): `src/rag_agent/agent.py`

### Knowledge and tools

- [Ingestion](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/ingest.py): `src/rag_agent/ingest.py`
- [Embeddings](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/embeddings.py): `src/rag_agent/embeddings.py`
- [Vector store access](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/vectorstore.py): `src/rag_agent/vectorstore.py`
- [Chroma index](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/vectorstore.py): `src/rag_agent/vectorstore.py`
- [Agent tools](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/tools.py): `src/rag_agent/tools.py`
- [Model factories](https://github.com/theborulesai/agentic-rag-assistant/blob/main/src/rag_agent/llms.py): `src/rag_agent/llms.py`
- [Sample documents](https://github.com/theborulesai/agentic-rag-assistant/tree/main/data/sample_docs): `data/sample_docs`

### Tracing and evaluation

- **LangSmith**
- [Evaluation suite](https://github.com/theborulesai/agentic-rag-assistant/blob/main/evals/run_evals.py): `evals/run_evals.py`

### Other components

- **User**
- **OpenAI models**
- **Web search**

## Connections

- User → Chat UI: asks
- Chat UI → Stream state: submits
- Stream state → FastAPI: POST chat
- FastAPI → Stream bridge: streams events
- Stream bridge → ReAct agent: consumes astream
- ReAct agent → Agent tools: dispatches tools
- ReAct agent → Model factories: uses models
- Model factories → OpenAI models: calls
- Agent tools → Vector store access: retrieves documents
- Vector store access → Chroma index: reads and writes
- Agent tools → Web search: searches web
- ReAct agent → Thread memory: checkpoints threads
- Stream bridge → Event schemas: formats events
- Stream bridge → LangSmith: auto-traces
- Stream bridge → Stream state: SSE events
- Stream state → SSE parser: parses stream
- SSE parser → Stream state: yields events
- Chat UI → Document upload: offers upload
- Document upload → API client: uploads files
- API client → FastAPI: POST ingest
- FastAPI → Ingestion: ingests files
- Sample documents → Ingestion: seeded on boot
- Ingestion → Embeddings: embeds chunks
- Embeddings → OpenAI models: requests embeddings
- Ingestion → Vector store access: persists chunks
- Evaluation suite → LangSmith: runs evaluations