# ftmehoseini/rastattbot architecture

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

- Interactive diagram: https://gitdiagram.com/ftmehoseini/rastattbot
- Repository: https://github.com/ftmehoseini/rastattbot

## Overview

Rasta Admin Bot is a Persian-language organizational administration bot. Employees and administrators interact through the bot: attendance actions and reports, leave requests and two-step decisions, and meal ordering and menu administration are handled by application services, with results delivered as messages or Excel files. Scheduled reminders and food broadcasts form a separate worker-driven path. The graph preserves the documented product areas and central policy, access-control, and audit responsibilities. Some handler and service wiring is unsampled, so uncertain links are omitted or marked unverified.

Main entry points: [`app/application/services/attendance_service.py`](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/attendance_service.py) (Attendance service), [`app/application/services/food_service.py`](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/food_service.py) (Food service), [`app/presentation/bot/handlers`](https://github.com/ftmehoseini/rastattbot/tree/main/app/presentation/bot/handlers) (Bot handlers), [`app/application/services/leave_service.py`](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/leave_service.py) (Leave service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Bot interface"]
  node_bot["Bot runtime<br/>[main.py]"]
  node_bot_handlers["Bot handlers"]
end

subgraph group_application["Application workflows"]
  node_attendance["Attendance service"]
  node_leave["Leave service<br/>[leave_service.py]"]
  node_food["Food service<br/>[food_service.py]"]
  node_users["User service<br/>[user_service.py]"]
  node_approval["Approval service"]
  node_reminders["Reminder use cases<br/>[reminders.py]"]
  node_broadcast["Food broadcast<br/>[food_broadcast.py]"]
end

subgraph group_domain["Business rules"]
  node_attendance_rules["Attendance calculations<br/>[calculation.py]"]
  node_approval_rules["Approval engine<br/>[engine.py]"]
  node_user_models[("User and roles<br/>[models.py]")]
  node_food_models[("Food records<br/>[models.py]")]
  node_audit_models[("Audit records<br/>[models.py]")]
end

subgraph group_infrastructure["Persistence and delivery"]
  node_attendance_repo["Attendance repository<br/>[attendance.py]"]
  node_food_repo["Food repository<br/>[food.py]"]
  node_users_repo["User repository<br/>[users.py]"]
  node_audit_repo["Audit repository<br/>[audit.py]"]
  node_tasks["Background jobs<br/>[jobs.py]"]
  node_messenger["Messenger transport<br/>[messenger.py]"]
  node_excel["Excel reports<br/>[reports.py]"]
  node_menu_parser["Menu import<br/>[menu_parser.py]"]
end

subgraph group_shared["Shared services"]
  node_policy["Organization policy<br/>[policy.py]"]
  node_rbac["Access control<br/>[rbac.py]"]
  node_clock["Local time service<br/>[clock.py]"]
  node_jalali["Jalali dates<br/>[jalali.py]"]
end

node_employee(("Employee"))
node_administrator(("Administrator"))

node_employee -->|"starts interaction"| node_bot
node_administrator -->|"uses admin flows"| node_bot
node_bot -->|"dispatches updates"| node_bot_handlers
node_bot -->|"creates transport"| node_messenger
node_bot_handlers -.->|"invokes"| node_attendance
node_bot_handlers -.->|"invokes"| node_leave
node_bot_handlers -.->|"invokes"| node_food
node_bot_handlers -->|"invokes"| node_users
node_bot_handlers -->|"exports reports"| node_excel
node_attendance -->|"reads and writes"| node_attendance_repo
node_attendance -->|"calculates"| node_attendance_rules
node_attendance -->|"uses rules"| node_policy
node_attendance -->|"gets local time"| node_clock
node_leave -->|"delegates decisions"| node_approval
node_leave -->|"checks attendance"| node_attendance
node_leave -->|"uses workflow rules"| node_approval_rules
node_leave -->|"uses rules"| node_policy
node_approval -->|"evaluates decisions"| node_approval_rules
node_food -->|"reads and writes"| node_food_repo
node_food -->|"parses menu files"| node_menu_parser
node_food -->|"looks up users"| node_users_repo
node_users -->|"reads and writes"| node_users_repo
node_users -->|"checks permissions"| node_rbac
node_attendance -->|"checks permissions"| node_rbac
node_food -->|"checks permissions"| node_rbac
node_users -->|"records changes"| node_audit_repo
node_food -->|"records actions"| node_audit_repo
node_tasks -->|"runs use case"| node_reminders
node_tasks -->|"runs use case"| node_broadcast
node_tasks -->|"sends notifications"| node_messenger
node_reminders -.->|"sends reminders"| node_employee
node_broadcast -.->|"announces menu"| node_employee
node_messenger -->|"delivers messages"| node_employee
node_attendance -->|"formats dates"| node_jalali
node_food -->|"formats dates"| node_jalali

click node_bot "https://github.com/ftmehoseini/rastattbot/blob/main/app/presentation/bot/main.py"
click node_bot_handlers "https://github.com/ftmehoseini/rastattbot/tree/main/app/presentation/bot/handlers"
click node_attendance "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/attendance_service.py"
click node_leave "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/leave_service.py"
click node_food "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/food_service.py"
click node_users "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/user_service.py"
click node_approval "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/approval_service.py"
click node_reminders "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/use_cases/reminders.py"
click node_broadcast "https://github.com/ftmehoseini/rastattbot/blob/main/app/application/use_cases/food_broadcast.py"
click node_attendance_rules "https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/attendance/calculation.py"
click node_approval_rules "https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/approvals/engine.py"
click node_user_models "https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/users/models.py"
click node_food_models "https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/food/models.py"
click node_audit_models "https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/audit/models.py"
click node_attendance_repo "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/attendance.py"
click node_food_repo "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/food.py"
click node_users_repo "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/users.py"
click node_audit_repo "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/audit.py"
click node_tasks "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/tasks/jobs.py"
click node_messenger "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/integrations/messenger.py"
click node_excel "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/excel/reports.py"
click node_menu_parser "https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/excel/menu_parser.py"
click node_policy "https://github.com/ftmehoseini/rastattbot/blob/main/app/core/config/policy.py"
click node_rbac "https://github.com/ftmehoseini/rastattbot/blob/main/app/core/security/rbac.py"
click node_clock "https://github.com/ftmehoseini/rastattbot/blob/main/app/core/utils/clock.py"
click node_jalali "https://github.com/ftmehoseini/rastattbot/blob/main/app/core/utils/jalali.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_bot_handlers toneBlue
class node_attendance,node_leave,node_food,node_users,node_approval,node_reminders,node_broadcast toneAmber
class node_attendance_rules,node_approval_rules,node_user_models,node_food_models,node_audit_models toneMint
class node_attendance_repo,node_food_repo,node_users_repo,node_audit_repo,node_tasks,node_messenger,node_excel,node_menu_parser toneRose
class node_policy,node_rbac,node_clock,node_jalali,node_employee,node_administrator toneIndigo
```

## Components

### Bot interface

- [Bot runtime](https://github.com/ftmehoseini/rastattbot/blob/main/app/presentation/bot/main.py): `app/presentation/bot/main.py`
- [Bot handlers](https://github.com/ftmehoseini/rastattbot/tree/main/app/presentation/bot/handlers): `app/presentation/bot/handlers`

### Application workflows

- [Attendance service](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/attendance_service.py): `app/application/services/attendance_service.py`
- [Leave service](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/leave_service.py): `app/application/services/leave_service.py`
- [Food service](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/food_service.py): `app/application/services/food_service.py`
- [User service](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/user_service.py): `app/application/services/user_service.py`
- [Approval service](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/services/approval_service.py): `app/application/services/approval_service.py`
- [Reminder use cases](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/use_cases/reminders.py): `app/application/use_cases/reminders.py`
- [Food broadcast](https://github.com/ftmehoseini/rastattbot/blob/main/app/application/use_cases/food_broadcast.py): `app/application/use_cases/food_broadcast.py`

### Business rules

- [Attendance calculations](https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/attendance/calculation.py): `app/domain/attendance/calculation.py`
- [Approval engine](https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/approvals/engine.py): `app/domain/approvals/engine.py`
- [User and roles](https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/users/models.py): `app/domain/users/models.py`
- [Food records](https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/food/models.py): `app/domain/food/models.py`
- [Audit records](https://github.com/ftmehoseini/rastattbot/blob/main/app/domain/audit/models.py): `app/domain/audit/models.py`

### Persistence and delivery

- [Attendance repository](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/attendance.py): `app/infrastructure/repositories/attendance.py`
- [Food repository](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/food.py): `app/infrastructure/repositories/food.py`
- [User repository](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/users.py): `app/infrastructure/repositories/users.py`
- [Audit repository](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/repositories/audit.py): `app/infrastructure/repositories/audit.py`
- [Background jobs](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/tasks/jobs.py): `app/infrastructure/tasks/jobs.py`
- [Messenger transport](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/integrations/messenger.py): `app/infrastructure/integrations/messenger.py`
- [Excel reports](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/excel/reports.py): `app/infrastructure/excel/reports.py`
- [Menu import](https://github.com/ftmehoseini/rastattbot/blob/main/app/infrastructure/excel/menu_parser.py): `app/infrastructure/excel/menu_parser.py`

### Shared services

- [Organization policy](https://github.com/ftmehoseini/rastattbot/blob/main/app/core/config/policy.py): `app/core/config/policy.py`
- [Access control](https://github.com/ftmehoseini/rastattbot/blob/main/app/core/security/rbac.py): `app/core/security/rbac.py`
- [Local time service](https://github.com/ftmehoseini/rastattbot/blob/main/app/core/utils/clock.py): `app/core/utils/clock.py`
- [Jalali dates](https://github.com/ftmehoseini/rastattbot/blob/main/app/core/utils/jalali.py): `app/core/utils/jalali.py`

### Other components

- **Employee**
- **Administrator**

## Connections

- Employee → Bot runtime: starts interaction (evidence: `README.md`)
- Administrator → Bot runtime: uses admin flows (evidence: `README.md`)
- Bot runtime → Bot handlers: dispatches updates (evidence: `app/presentation/bot/main.py`)
- Bot runtime → Messenger transport: creates transport (evidence: `app/presentation/bot/main.py`)
- Bot handlers → Attendance service: invokes
- Bot handlers → Leave service: invokes
- Bot handlers → Food service: invokes
- Bot handlers → User service: invokes (evidence: `app/presentation/bot/handlers/admin.py`)
- Bot handlers → Excel reports: exports reports (evidence: `app/presentation/bot/handlers/admin.py`)
- Attendance service → Attendance repository: reads and writes (evidence: `app/application/services/attendance_service.py`)
- Attendance service → Attendance calculations: calculates (evidence: `app/application/services/attendance_service.py`)
- Attendance service → Organization policy: uses rules (evidence: `app/application/services/attendance_service.py`)
- Attendance service → Local time service: gets local time (evidence: `app/application/services/attendance_service.py`)
- Leave service → Approval service: delegates decisions (evidence: `app/application/services/leave_service.py`)
- Leave service → Attendance service: checks attendance (evidence: `app/application/services/leave_service.py`)
- Leave service → Approval engine: uses workflow rules (evidence: `app/application/services/leave_service.py`)
- Leave service → Organization policy: uses rules (evidence: `app/application/services/leave_service.py`)
- Approval service → Approval engine: evaluates decisions (evidence: `app/application/services/approval_service.py`)
- Food service → Food repository: reads and writes (evidence: `app/application/services/food_service.py`)
- Food service → Menu import: parses menu files (evidence: `app/application/services/food_service.py`)
- Food service → User repository: looks up users (evidence: `app/application/services/food_service.py`)
- User service → User repository: reads and writes (evidence: `app/application/services/user_service.py`)
- User service → Access control: checks permissions (evidence: `app/application/services/user_service.py`)
- Attendance service → Access control: checks permissions (evidence: `app/application/services/attendance_service.py`)
- Food service → Access control: checks permissions (evidence: `app/application/services/food_service.py`)
- User service → Audit repository: records changes (evidence: `app/application/services/user_service.py`)
- Food service → Audit repository: records actions (evidence: `app/application/services/food_service.py`)
- Background jobs → Reminder use cases: runs use case (evidence: `app/infrastructure/tasks/jobs.py`)
- Background jobs → Food broadcast: runs use case (evidence: `app/infrastructure/tasks/jobs.py`)
- Background jobs → Messenger transport: sends notifications (evidence: `app/infrastructure/tasks/jobs.py`)
- Reminder use cases → Employee: sends reminders
- Food broadcast → Employee: announces menu
- Messenger transport → Employee: delivers messages (evidence: `README.md`)
- Attendance service → Jalali dates: formats dates (evidence: `app/application/services/attendance_service.py`)
- Food service → Jalali dates: formats dates (evidence: `app/application/services/food_service.py`)