# labriiola/nyp-seg-bot architecture

> Architecture diagram of the GitHub repository labriiola/nyp-seg-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/labriiola/nyp-seg-bot
- Repository: https://github.com/labriiola/nyp-seg-bot

## Overview

This is a Telegram advising bot for Nanyang Polytechnic’s School of Engineering. Users can browse diploma details and cut-off points through inline menus, or ask course-related questions; the message handler adds any selected-diploma context before requesting a Gemini response. Configuration loads the course catalog and credentials, while a separate HTTP health endpoint runs alongside polling. The graph reflects the sampled runtime; the catalog’s internal schema and any deployment-side health-check caller were not inspected.

Main entry points: [`bot.py`](https://github.com/labriiola/nyp-seg-bot/blob/main/bot.py) (Bot runtime), [`handlers.py`](https://github.com/labriiola/nyp-seg-bot/blob/main/handlers.py) (Course menus and chat), [`ai_service.py`](https://github.com/labriiola/nyp-seg-bot/blob/main/ai_service.py) (AI response service), [`config.py`](https://github.com/labriiola/nyp-seg-bot/blob/main/config.py) (Settings and loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram runtime"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_handlers["Course menus and chat<br/>[handlers.py]"]
end

subgraph group_advising["Course advising"]
  node_config["Settings and loader<br/>[config.py]"]
  node_catalog["SEG course catalog<br/>[seg_courses.json]"]
  node_ai["AI response service<br/>[ai_service.py]"]
end

subgraph group_operations["Health service"]
  node_health["HTTP health endpoint<br/>[server.py]"]
end

node_user(("Telegram user"))
node_gemini["Gemini API"]

node_user -->|"sends commands"| node_bot
node_bot -->|"registers handlers"| node_handlers
node_handlers -->|"reads course data"| node_config
node_config -->|"loads JSON"| node_catalog
node_handlers -->|"requests answer"| node_ai
node_ai -->|"uses key and catalog"| node_config
node_ai -->|"generates response"| node_gemini
node_bot -->|"starts server"| node_health

click node_bot "https://github.com/labriiola/nyp-seg-bot/blob/main/bot.py"
click node_handlers "https://github.com/labriiola/nyp-seg-bot/blob/main/handlers.py"
click node_config "https://github.com/labriiola/nyp-seg-bot/blob/main/config.py"
click node_catalog "https://github.com/labriiola/nyp-seg-bot/blob/main/seg_courses.json"
click node_ai "https://github.com/labriiola/nyp-seg-bot/blob/main/ai_service.py"
click node_health "https://github.com/labriiola/nyp-seg-bot/blob/main/server.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_bot,node_handlers,node_user toneBlue
class node_config,node_catalog,node_ai toneAmber
class node_health,node_gemini toneMint
```

## Components

### Telegram runtime

- [Bot runtime](https://github.com/labriiola/nyp-seg-bot/blob/main/bot.py): `bot.py`
- [Course menus and chat](https://github.com/labriiola/nyp-seg-bot/blob/main/handlers.py): `handlers.py`

### Course advising

- [Settings and loader](https://github.com/labriiola/nyp-seg-bot/blob/main/config.py): `config.py`
- [SEG course catalog](https://github.com/labriiola/nyp-seg-bot/blob/main/seg_courses.json): `seg_courses.json`
- [AI response service](https://github.com/labriiola/nyp-seg-bot/blob/main/ai_service.py): `ai_service.py`

### Health service

- [HTTP health endpoint](https://github.com/labriiola/nyp-seg-bot/blob/main/server.py): `server.py`

### Other components

- **Telegram user**
- **Gemini API**

## Connections

- Telegram user → Bot runtime: sends commands (evidence: `bot.py`)
- Bot runtime → Course menus and chat: registers handlers (evidence: `bot.py`)
- Course menus and chat → Settings and loader: reads course data (evidence: `handlers.py`)
- Settings and loader → SEG course catalog: loads JSON (evidence: `config.py`)
- Course menus and chat → AI response service: requests answer (evidence: `handlers.py`)
- AI response service → Settings and loader: uses key and catalog (evidence: `ai_service.py`)
- AI response service → Gemini API: generates response (evidence: `ai_service.py`)
- Bot runtime → HTTP health endpoint: starts server (evidence: `bot.py`)
