# jason-hooo/isrc-rag-bot architecture

> Architecture diagram of the GitHub repository jason-hooo/isrc-rag-bot, 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/jason-hooo/isrc-rag-bot
- Repository: https://github.com/jason-hooo/isrc-rag-bot

## Overview

原寶 is a Chainlit conversational assistant for NCCU’s Indigenous Student Resource Center. Users choose Campus Resources or Indigenous Issues, ask questions over multiple turns, and receive streamed answers with source excerpts. The backend builds or loads a metadata-tagged Qdrant index from local documents, then uses an agent to decide whether to retrieve; resource questions can be category-filtered and fall back to broader search. Conversation turns are logged to Google Sheets. The graph reflects README-described capabilities where source excerpts are incomplete; some internal wiring is therefore left unspecified.

Main entry points: [`src/rag.py`](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py) (Filtered retrieval), [`app.py`](https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py) (Chat interface), [`src/sheets_logger.py`](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/sheets_logger.py) (Sheets logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat experience"]
  node_chainlit["Chat interface<br/>[app.py]"]
  node_topic["Topic selection<br/>[app.py]"]
  node_stream["Stream and cite<br/>[app.py]"]
  node_turnlog["Turn logging<br/>[app.py]"]
end

subgraph group_rag["RAG workflow"]
  node_service["Multi-turn service<br/>[rag.py]"]
  node_agent["Agent workflow<br/>[rag.py]"]
  node_classifier["Category classification<br/>[rag.py]"]
  node_tool["Knowledge-base tool<br/>[rag.py]"]
  node_retrieval["Filtered retrieval<br/>[rag.py]"]
  node_fallback["Global fallback<br/>[rag.py]"]
  node_reranker["Result reranking<br/>[rag.py]"]
end

subgraph group_knowledge["Knowledge indexing"]
  node_indexing["Document indexing<br/>[rag.py]"]
  node_metadata["Topic and category metadata<br/>[rag.py]"]
end

subgraph group_integrations["External services"]
  node_qdrant[("Qdrant vector store")]
  node_jinaembed["Jina embeddings"]
  node_jinarerank["Jina reranker"]
  node_gemini["Gemini model"]
  node_sheetslogger["Sheets logger<br/>[sheets_logger.py]"]
  node_sheets[("Google Sheets")]
end

node_student(("Student or faculty"))
node_documents["ISRC source documents"]

node_student -->|"asks"| node_chainlit
node_chainlit -->|"offers topics"| node_topic
node_topic -->|"creates session"| node_service
node_chainlit -->|"sends question"| node_service
node_service -->|"runs workflow"| node_agent
node_agent -->|"classifies resources"| node_classifier
node_agent -->|"calls when needed"| node_tool
node_tool -->|"searches topic"| node_retrieval
node_retrieval -->|"queries vectors"| node_qdrant
node_qdrant -->|"returns matches"| node_retrieval
node_retrieval -.->|"broadens search"| node_fallback
node_retrieval -->|"ranks matches"| node_reranker
node_reranker -->|"uses model"| node_jinarerank
node_indexing -->|"loads files"| node_documents
node_indexing -->|"assigns labels"| node_metadata
node_indexing -->|"embeds chunks"| node_jinaembed
node_indexing -->|"writes index"| node_qdrant
node_agent -->|"generates response"| node_gemini
node_service -->|"streams answer and sources"| node_stream
node_stream -->|"displays response"| node_student
node_chainlit -->|"records completed turn"| node_turnlog
node_turnlog -->|"calls logger"| node_sheetslogger
node_sheetslogger -->|"appends row"| node_sheets

click node_chainlit "https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py"
click node_topic "https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py"
click node_stream "https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py"
click node_turnlog "https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py"
click node_service "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_agent "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_classifier "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_tool "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_retrieval "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_fallback "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_reranker "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_indexing "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_metadata "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py"
click node_sheetslogger "https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/sheets_logger.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_chainlit,node_topic,node_stream,node_turnlog toneBlue
class node_service,node_agent,node_classifier,node_tool,node_retrieval,node_fallback,node_reranker toneAmber
class node_indexing,node_metadata toneMint
class node_qdrant,node_jinaembed,node_jinarerank,node_gemini,node_sheetslogger,node_sheets toneRose
class node_student,node_documents toneIndigo
```

## Components

### Chat experience

- [Chat interface](https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py): `app.py`
- [Topic selection](https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py): `app.py`
- [Stream and cite](https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py): `app.py`
- [Turn logging](https://github.com/jason-hooo/isrc-rag-bot/blob/main/app.py): `app.py`

### RAG workflow

- [Multi-turn service](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Agent workflow](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Category classification](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Knowledge-base tool](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Filtered retrieval](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Global fallback](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Result reranking](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`

### Knowledge indexing

- [Document indexing](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`
- [Topic and category metadata](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/rag.py): `src/rag.py`

### External services

- **Qdrant vector store**
- **Jina embeddings**
- **Jina reranker**
- **Gemini model**
- [Sheets logger](https://github.com/jason-hooo/isrc-rag-bot/blob/main/src/sheets_logger.py): `src/sheets_logger.py`
- **Google Sheets**

### Other components

- **Student or faculty**
- **ISRC source documents**

## Connections

- Student or faculty → Chat interface: asks
- Chat interface → Topic selection: offers topics
- Topic selection → Multi-turn service: creates session
- Chat interface → Multi-turn service: sends question
- Multi-turn service → Agent workflow: runs workflow
- Agent workflow → Category classification: classifies resources
- Agent workflow → Knowledge-base tool: calls when needed
- Knowledge-base tool → Filtered retrieval: searches topic
- Filtered retrieval → Qdrant vector store: queries vectors
- Qdrant vector store → Filtered retrieval: returns matches
- Filtered retrieval → Global fallback: broadens search
- Filtered retrieval → Result reranking: ranks matches
- Result reranking → Jina reranker: uses model
- Document indexing → ISRC source documents: loads files
- Document indexing → Topic and category metadata: assigns labels
- Document indexing → Jina embeddings: embeds chunks
- Document indexing → Qdrant vector store: writes index
- Agent workflow → Gemini model: generates response
- Multi-turn service → Stream and cite: streams answer and sources
- Stream and cite → Student or faculty: displays response
- Chat interface → Turn logging: records completed turn
- Turn logging → Sheets logger: calls logger
- Sheets logger → Google Sheets: appends row