# xytex-s/eam-ai-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/xytex-s/eam-ai-chatbot
- Repository: https://github.com/xytex-s/eam-ai-chatbot

## Overview

This is a local Flask chatbot for SHU student-support questions, with sourced answers from university pages, fixed crisis responses, nearby-place recommendations, and streamed answers. The main workflow routes a question through safety and place checks before retrieval and local-model generation. Its knowledge pipeline discovers pages, collects and chunks them, then builds the searchable index. The graph preserves these distinct stages and the optional OpenStreetMap integration. Some runtime details are unsampled; uncertain links are omitted.

Main entry points: [`chatbot/app.py`](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/app.py) (Flask API), [`chatbot/rag.py`](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/rag.py) (RAG workflow), [`paging/collect_pages.py`](https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/collect_pages.py) (Page collection), [`chatbot/build_index.py`](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/build_index.py) (Index building)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Knowledge preparation"]
  node_page_discovery["Page discovery<br/>[find_pages.py]"]
  node_shu_pages["SHU pages"]
  node_page_collection["Page collection<br/>[collect_pages.py]"]
  node_chunks["Page chunks<br/>[chunks.json]"]
  node_index_build["Index building<br/>[build_index.py]"]
end

subgraph group_answering["Question answering"]
  node_search_index[("Search index<br/>[index.pt]")]
  node_rag["RAG workflow<br/>[rag.py]"]
  node_local_model["Local language model<br/>[rag.py]"]
end

subgraph group_special["Specialized responses"]
  node_safety["Safety check<br/>[safety.py]"]
  node_places["Nearby places<br/>[places.py]"]
end

subgraph group_interface["Web interface"]
  node_chat_ui["Chat page<br/>[test_chat.html]"]
  node_api["Flask API<br/>[app.py]"]
end

node_student(("Student"))
node_overpass["OpenStreetMap"]

node_student -->|"asks"| node_chat_ui
node_chat_ui -->|"sends question"| node_api
node_api -->|"checks first"| node_safety
node_api -->|"checks next"| node_places
node_api -->|"requests answer"| node_rag
node_rag -->|"searches"| node_search_index
node_rag -->|"generates answer"| node_local_model
node_places -->|"queries"| node_overpass
node_page_discovery -->|"finds URLs"| node_shu_pages
node_page_collection -->|"downloads"| node_shu_pages
node_page_collection -->|"writes chunks"| node_chunks
node_index_build -->|"reads chunks"| node_chunks
node_index_build -->|"builds index"| node_search_index

click node_page_discovery "https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/find_pages.py"
click node_page_collection "https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/collect_pages.py"
click node_chunks "https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/data/chunks.json"
click node_index_build "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/build_index.py"
click node_search_index "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/data/index.pt"
click node_chat_ui "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/templates/test_chat.html"
click node_api "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/app.py"
click node_safety "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/safety.py"
click node_places "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/places.py"
click node_rag "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/rag.py"
click node_local_model "https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/rag.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_page_discovery,node_shu_pages,node_page_collection,node_chunks,node_index_build toneBlue
class node_search_index,node_rag,node_local_model toneAmber
class node_safety,node_places toneMint
class node_chat_ui,node_api toneRose
class node_student,node_overpass toneIndigo
```

## Components

### Knowledge preparation

- [Page discovery](https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/find_pages.py): `paging/find_pages.py`
- **SHU pages**
- [Page collection](https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/collect_pages.py): `paging/collect_pages.py`
- [Page chunks](https://github.com/xytex-s/eam-ai-chatbot/blob/main/paging/data/chunks.json): `paging/data/chunks.json`
- [Index building](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/build_index.py): `chatbot/build_index.py`

### Question answering

- [Search index](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/data/index.pt): `chatbot/data/index.pt`
- [RAG workflow](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/rag.py): `chatbot/rag.py`
- [Local language model](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/rag.py): `chatbot/rag.py`

### Specialized responses

- [Safety check](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/safety.py): `chatbot/safety.py`
- [Nearby places](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/places.py): `chatbot/places.py`

### Web interface

- [Chat page](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/templates/test_chat.html): `chatbot/templates/test_chat.html`
- [Flask API](https://github.com/xytex-s/eam-ai-chatbot/blob/main/chatbot/app.py): `chatbot/app.py`

### Other components

- **Student**
- **OpenStreetMap**

## Connections

- Student → Chat page: asks (evidence: `README.md`)
- Chat page → Flask API: sends question (evidence: `chatbot/app.py`)
- Flask API → Safety check: checks first (evidence: `chatbot/app.py`)
- Flask API → Nearby places: checks next (evidence: `chatbot/app.py`)
- Flask API → RAG workflow: requests answer (evidence: `README.md`)
- RAG workflow → Search index: searches (evidence: `chatbot/rag.py`)
- RAG workflow → Local language model: generates answer (evidence: `chatbot/rag.py`)
- Nearby places → OpenStreetMap: queries (evidence: `chatbot/places.py`)
- Page discovery → SHU pages: finds URLs (evidence: `paging/find_pages.py`)
- Page collection → SHU pages: downloads (evidence: `paging/collect_pages.py`)
- Page collection → Page chunks: writes chunks (evidence: `README.md`)
- Index building → Page chunks: reads chunks (evidence: `README.md`)
- Index building → Search index: builds index (evidence: `README.md`)