# yzansawadi/web_seeker_bot architecture

> Architecture diagram of the GitHub repository yzansawadi/web_seeker_bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yzansawadi/web_seeker_bot
- Repository: https://github.com/yzansawadi/web_seeker_bot

## Overview

This repository is an Arabic Telegram assistant for building and viewing IUST course schedules. Students choose courses or request an optimized schedule; the bot loads course and meeting data, formats a text/PDF result, and can refresh the source schedule. Separate capabilities cover all-course schedule PDFs and usage tracking with owner-facing administration. The graph reflects the documented workflow and sampled code; some bot handlers are omitted from the excerpts, so uncertain internal links are not shown.

Main entry points: [`bot.py`](https://github.com/yzansawadi/web_seeker_bot/blob/main/bot.py) (Bot workflow), [`notifier.py`](https://github.com/yzansawadi/web_seeker_bot/blob/main/notifier.py) (User tracking), [`schedule_data.py`](https://github.com/yzansawadi/web_seeker_bot/blob/main/schedule_data.py) (Course loader), [`extract_schedule.py`](https://github.com/yzansawadi/web_seeker_bot/blob/main/extract_schedule.py) (Schedule scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student scheduling"]
  node_bot["Bot workflow<br/>[bot.py]"]
  node_optimizer["Best-schedule search"]
end

subgraph group_data["Schedule data"]
  node_subjects_file["Course-year map<br/>[subjects.xlsx]"]
  node_schedule_file["Meeting data"]
  node_schedule_data["Course loader<br/>[schedule_data.py]"]
  node_scraper["Schedule scraper"]
end

subgraph group_output["Schedule output"]
  node_pdf_export["Schedule PDF renderer<br/>[pdf_export.py]"]
  node_selected_pdf["Selected-course PDF"]
  node_arabic["Arabic text shaping<br/>[arabic_text.py]"]
  node_fonts["Arabic font"]
end

subgraph group_tracking["Usage tracking"]
  node_redis[("Redis storage")]
  node_notifier["User tracking<br/>[notifier.py]"]
  node_admin["Owner commands<br/>[notifier_admin.py]"]
end

node_student_user(("Student"))
node_telegram(("Telegram"))
node_university(("University schedule site"))
node_owner(("Bot owner"))
node_dashboard(("Activity dashboard"))

node_student_user -->|"sends requests"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"sends results"| node_telegram
node_bot -->|"loads courses"| node_schedule_data
node_schedule_data -->|"reads mapping"| node_subjects_file
node_schedule_data -->|"reads meetings"| node_schedule_file
node_bot -->|"requests optimization"| node_optimizer
node_bot -->|"renders schedule PDF"| node_pdf_export
node_bot -->|"renders selected PDF"| node_selected_pdf
node_pdf_export -->|"shapes Arabic text"| node_arabic
node_selected_pdf -->|"shapes Arabic text"| node_arabic
node_pdf_export -->|"loads font"| node_fonts
node_selected_pdf -->|"loads font"| node_fonts
node_bot -->|"starts refresh"| node_scraper
node_scraper -->|"fetches schedule"| node_university
node_scraper -->|"replaces data"| node_schedule_file
node_bot -->|"records activity"| node_notifier
node_notifier -.->|"reads and writes"| node_redis
node_notifier -.->|"sends activity"| node_dashboard
node_owner -->|"sends commands"| node_telegram
node_telegram -->|"delivers commands"| node_admin
node_admin -->|"reviews records"| node_notifier
node_admin -->|"replies with reports"| node_telegram

click node_bot "https://github.com/yzansawadi/web_seeker_bot/blob/main/bot.py"
click node_subjects_file "https://github.com/yzansawadi/web_seeker_bot/blob/main/subjects.xlsx"
click node_schedule_file "https://github.com/yzansawadi/web_seeker_bot/blob/main/IUST_schedule_full.xlsx"
click node_schedule_data "https://github.com/yzansawadi/web_seeker_bot/blob/main/schedule_data.py"
click node_scraper "https://github.com/yzansawadi/web_seeker_bot/blob/main/extract_schedule.py"
click node_optimizer "https://github.com/yzansawadi/web_seeker_bot/blob/main/schedule_optimizer.py"
click node_pdf_export "https://github.com/yzansawadi/web_seeker_bot/blob/main/pdf_export.py"
click node_selected_pdf "https://github.com/yzansawadi/web_seeker_bot/blob/main/selected_schedule_pdf.py"
click node_arabic "https://github.com/yzansawadi/web_seeker_bot/blob/main/arabic_text.py"
click node_fonts "https://github.com/yzansawadi/web_seeker_bot/tree/main/fonts"
click node_notifier "https://github.com/yzansawadi/web_seeker_bot/blob/main/notifier.py"
click node_admin "https://github.com/yzansawadi/web_seeker_bot/blob/main/notifier_admin.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_optimizer toneBlue
class node_subjects_file,node_schedule_file,node_schedule_data,node_scraper toneAmber
class node_pdf_export,node_selected_pdf,node_arabic,node_fonts toneMint
class node_redis,node_notifier,node_admin toneRose
class node_student_user,node_telegram,node_university,node_owner,node_dashboard toneIndigo
```

## Components

### Student scheduling

- [Bot workflow](https://github.com/yzansawadi/web_seeker_bot/blob/main/bot.py): `bot.py`
- [Best-schedule search](https://github.com/yzansawadi/web_seeker_bot/blob/main/schedule_optimizer.py): `schedule_optimizer.py`

### Schedule data

- [Course-year map](https://github.com/yzansawadi/web_seeker_bot/blob/main/subjects.xlsx): `subjects.xlsx`
- [Meeting data](https://github.com/yzansawadi/web_seeker_bot/blob/main/IUST_schedule_full.xlsx): `IUST_schedule_full.xlsx`
- [Course loader](https://github.com/yzansawadi/web_seeker_bot/blob/main/schedule_data.py): `schedule_data.py`
- [Schedule scraper](https://github.com/yzansawadi/web_seeker_bot/blob/main/extract_schedule.py): `extract_schedule.py`

### Schedule output

- [Schedule PDF renderer](https://github.com/yzansawadi/web_seeker_bot/blob/main/pdf_export.py): `pdf_export.py`
- [Selected-course PDF](https://github.com/yzansawadi/web_seeker_bot/blob/main/selected_schedule_pdf.py): `selected_schedule_pdf.py`
- [Arabic text shaping](https://github.com/yzansawadi/web_seeker_bot/blob/main/arabic_text.py): `arabic_text.py`
- [Arabic font](https://github.com/yzansawadi/web_seeker_bot/tree/main/fonts): `fonts`

### Usage tracking

- **Redis storage**
- [User tracking](https://github.com/yzansawadi/web_seeker_bot/blob/main/notifier.py): `notifier.py`
- [Owner commands](https://github.com/yzansawadi/web_seeker_bot/blob/main/notifier_admin.py): `notifier_admin.py`

### Other components

- **Student**
- **Telegram**
- **University schedule site**
- **Bot owner**
- **Activity dashboard**

## Connections

- Student → Telegram: sends requests
- Telegram → Bot workflow: delivers updates
- Bot workflow → Telegram: sends results
- Bot workflow → Course loader: loads courses
- Course loader → Course-year map: reads mapping
- Course loader → Meeting data: reads meetings
- Bot workflow → Best-schedule search: requests optimization
- Bot workflow → Schedule PDF renderer: renders schedule PDF
- Bot workflow → Selected-course PDF: renders selected PDF
- Schedule PDF renderer → Arabic text shaping: shapes Arabic text
- Selected-course PDF → Arabic text shaping: shapes Arabic text
- Schedule PDF renderer → Arabic font: loads font
- Selected-course PDF → Arabic font: loads font
- Bot workflow → Schedule scraper: starts refresh
- Schedule scraper → University schedule site: fetches schedule
- Schedule scraper → Meeting data: replaces data
- Bot workflow → User tracking: records activity
- User tracking → Redis storage: reads and writes
- User tracking → Activity dashboard: sends activity
- Bot owner → Telegram: sends commands
- Telegram → Owner commands: delivers commands
- Owner commands → User tracking: reviews records
- Owner commands → Telegram: replies with reports