# matinghanbari/diningreservationbot architecture

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

- Interactive diagram: https://gitdiagram.com/matinghanbari/diningreservationbot
- Repository: https://github.com/matinghanbari/diningreservationbot

## Overview

This is a Persian-language Telegram bot for university dining reservations through Samad. Its main workflow takes a student's Telegram request through a screen handler and application use case, obtains or renews a Samad session, and makes the Samad request. Other documented branches cover automatic booking, forget-code sharing, account details, operator support, and an optional AI support chatbot. The README and source index support the layer boundaries and major capabilities; several feature-specific handlers and integrations were not excerpted, so uncertain internal calls are left unconnected.

Main entry points: [`src/bot/handlers`](https://github.com/matinghanbari/diningreservationbot/tree/main/src/bot/handlers) (Screen handlers), [`src/app/session.service.ts`](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/session.service.ts) (Session renewal), [`src/app/reservation.service.ts`](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/reservation.service.ts) (Menus and bookings), [`src/app/auth.service.ts`](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auth.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram experience"]
  node_handlers["Screen handlers"]
  node_botservices["Bot service access<br/>[services.ts]"]
end

subgraph group_application["Application services"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_reservation["Menus and bookings"]
  node_session["Session renewal<br/>[session.service.ts]"]
  node_auto["Automatic booking"]
  node_forget["Forget-code pool"]
  node_credit["Credit reminders"]
  node_profile["Account details<br/>[auth.service.ts]"]
  node_supportservice["Operator support<br/>[support.service.ts]"]
  node_chatbotservice["Support chatbot<br/>[chatbot.service.ts]"]
  node_admin["Admin controls<br/>[admin.service.ts]"]
end

subgraph group_samad["Samad integration"]
  node_gateway["Samad gateway<br/>[gateway.ts]"]
  node_client["Samad HTTP client<br/>[client.ts]"]
end

subgraph group_state["State and persistence"]
  node_redis[("Redis repositories")]
  node_sessioncache["Session cache<br/>[session.store.ts]"]
end

subgraph group_operations["Support and operations"]
  node_scheduler["Scheduled jobs<br/>[scheduler.ts]"]
end

node_students(("Students"))
node_telegram(("Telegram"))
node_samadplatform["Samad platform"]
node_openrouter["OpenRouter assistant"]
node_supportmessenger["Operator messaging"]

node_students -->|"send requests"| node_telegram
node_telegram -->|"deliver updates"| node_handlers
node_handlers -->|"access services"| node_botservices
node_handlers -->|"sign in"| node_auth
node_handlers -->|"browse and book"| node_reservation
node_handlers -->|"configure booking"| node_auto
node_handlers -->|"claim or donate"| node_forget
node_handlers -->|"view details"| node_profile
node_handlers -->|"send support"| node_supportservice
node_handlers -.->|"ask questions"| node_chatbotservice
node_handlers -->|"administer bot"| node_admin
node_auth -->|"establish session"| node_session
node_reservation -->|"use session"| node_session
node_session -->|"renew token"| node_gateway
node_auto -->|"reserve meals"| node_reservation
node_forget -->|"issue codes"| node_reservation
node_gateway -->|"make requests"| node_client
node_client -->|"call API"| node_samadplatform
node_auth -.->|"persist account"| node_redis
node_forget -.->|"store shared codes"| node_redis
node_supportservice -.->|"store tickets"| node_redis
node_session -->|"cache tokens"| node_sessioncache
node_scheduler -.->|"trigger booking"| node_auto
node_scheduler -.->|"trigger checks"| node_credit
node_chatbotservice -.->|"request answers"| node_openrouter
node_supportservice -.->|"route messages"| node_supportmessenger

click node_handlers "https://github.com/matinghanbari/diningreservationbot/tree/main/src/bot/handlers"
click node_botservices "https://github.com/matinghanbari/diningreservationbot/blob/main/src/bot/services.ts"
click node_auth "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auth.service.ts"
click node_reservation "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/reservation.service.ts"
click node_session "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/session.service.ts"
click node_auto "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auto-reserve.service.ts"
click node_forget "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/forget-code.service.ts"
click node_credit "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/credit-watch.service.ts"
click node_profile "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auth.service.ts"
click node_supportservice "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/support.service.ts"
click node_chatbotservice "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/chatbot.service.ts"
click node_admin "https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/admin.service.ts"
click node_gateway "https://github.com/matinghanbari/diningreservationbot/blob/main/src/samad/gateway.ts"
click node_client "https://github.com/matinghanbari/diningreservationbot/blob/main/src/samad/client.ts"
click node_redis "https://github.com/matinghanbari/diningreservationbot/tree/main/src/db/redis"
click node_sessioncache "https://github.com/matinghanbari/diningreservationbot/blob/main/src/cache/session.store.ts"
click node_scheduler "https://github.com/matinghanbari/diningreservationbot/blob/main/src/scheduler/scheduler.ts"

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_handlers,node_botservices toneBlue
class node_auth,node_reservation,node_session,node_auto,node_forget,node_credit,node_profile,node_supportservice,node_chatbotservice,node_admin toneAmber
class node_gateway,node_client,node_openrouter toneMint
class node_redis,node_sessioncache toneRose
class node_scheduler,node_students,node_telegram,node_samadplatform,node_supportmessenger toneIndigo
```

## Components

### Telegram experience

- [Screen handlers](https://github.com/matinghanbari/diningreservationbot/tree/main/src/bot/handlers): `src/bot/handlers`
- [Bot service access](https://github.com/matinghanbari/diningreservationbot/blob/main/src/bot/services.ts): `src/bot/services.ts`

### Application services

- [Authentication](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auth.service.ts): `src/app/auth.service.ts`
- [Menus and bookings](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/reservation.service.ts): `src/app/reservation.service.ts`
- [Session renewal](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/session.service.ts): `src/app/session.service.ts`
- [Automatic booking](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auto-reserve.service.ts): `src/app/auto-reserve.service.ts`
- [Forget-code pool](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/forget-code.service.ts): `src/app/forget-code.service.ts`
- [Credit reminders](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/credit-watch.service.ts): `src/app/credit-watch.service.ts`
- [Account details](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/auth.service.ts): `src/app/auth.service.ts`
- [Operator support](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/support.service.ts): `src/app/support.service.ts`
- [Support chatbot](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/chatbot.service.ts): `src/app/chatbot.service.ts`
- [Admin controls](https://github.com/matinghanbari/diningreservationbot/blob/main/src/app/admin.service.ts): `src/app/admin.service.ts`

### Samad integration

- [Samad gateway](https://github.com/matinghanbari/diningreservationbot/blob/main/src/samad/gateway.ts): `src/samad/gateway.ts`
- [Samad HTTP client](https://github.com/matinghanbari/diningreservationbot/blob/main/src/samad/client.ts): `src/samad/client.ts`

### State and persistence

- [Redis repositories](https://github.com/matinghanbari/diningreservationbot/tree/main/src/db/redis): `src/db/redis`
- [Session cache](https://github.com/matinghanbari/diningreservationbot/blob/main/src/cache/session.store.ts): `src/cache/session.store.ts`

### Support and operations

- [Scheduled jobs](https://github.com/matinghanbari/diningreservationbot/blob/main/src/scheduler/scheduler.ts): `src/scheduler/scheduler.ts`

### Other components

- **Students**
- **Telegram**
- **Samad platform**
- **OpenRouter assistant**
- **Operator messaging**

## Connections

- Students → Telegram: send requests
- Telegram → Screen handlers: deliver updates
- Screen handlers → Bot service access: access services (evidence: `src/bot/handlers/start.handler.ts`)
- Screen handlers → Authentication: sign in
- Screen handlers → Menus and bookings: browse and book
- Screen handlers → Automatic booking: configure booking
- Screen handlers → Forget-code pool: claim or donate
- Screen handlers → Account details: view details
- Screen handlers → Operator support: send support
- Screen handlers → Support chatbot: ask questions
- Screen handlers → Admin controls: administer bot (evidence: `src/bot/handlers/admin.handler.ts`)
- Authentication → Session renewal: establish session (evidence: `src/app/auth.service.ts`)
- Menus and bookings → Session renewal: use session (evidence: `src/app/reservation.service.ts`)
- Session renewal → Samad gateway: renew token
- Automatic booking → Menus and bookings: reserve meals (evidence: `src/app/auto-reserve.service.ts`)
- Forget-code pool → Menus and bookings: issue codes (evidence: `src/app/forget-code.service.ts`)
- Samad gateway → Samad HTTP client: make requests
- Samad HTTP client → Samad platform: call API
- Authentication → Redis repositories: persist account
- Forget-code pool → Redis repositories: store shared codes
- Operator support → Redis repositories: store tickets
- Session renewal → Session cache: cache tokens (evidence: `src/app/session.service.ts`)
- Scheduled jobs → Automatic booking: trigger booking
- Scheduled jobs → Credit reminders: trigger checks
- Support chatbot → OpenRouter assistant: request answers
- Operator support → Operator messaging: route messages
