# mikemin32/shipmentstrackbot architecture

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

- Interactive diagram: https://gitdiagram.com/mikemin32/shipmentstrackbot
- Repository: https://github.com/mikemin32/shipmentstrackbot

## Overview

Deliverybot is an allowlisted Telegram operations bot for managing clone shipments. Authorized users open a persistent, single-message workspace to browse status-grouped shipments, search and edit records, manage accounts and teams, archive or deliver shipments, and set reminders. The bot’s handlers coordinate workspace views and repository operations over SQLite; a background worker delivers manual and Expected Delivery reminders. The README documents the major capabilities, while some handler and worker internals were not excerpted, so those documented links use README evidence.

Main entry points: [`bot.py`](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot.py) (Bot startup), [`handlers/workspace.py`](https://github.com/mikemin32/shipmentstrackbot/blob/main/handlers/workspace.py) (Workspace handlers), [`database/repository.py`](https://github.com/mikemin32/shipmentstrackbot/blob/main/database/repository.py) (Shipment and reminder repositories), [`bot_ui/views.py`](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/views.py) (Workspace views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot startup<br/>[bot.py]"]
  node_auth["Allowlist middleware<br/>[auth.py]"]
end

subgraph group_workspace["Interactive workspace"]
  node_workspace_handler["Workspace handlers<br/>[workspace.py]"]
  node_workspace_engine["Workspace state and navigation<br/>[workspace.py]"]
  node_views["Workspace views<br/>[views.py]"]
  node_ui_keyboards["Workspace keyboards<br/>[keyboards.py]"]
end

subgraph group_operations["Shipment operations"]
  node_legacy_handlers["Command and shipment handlers<br/>[shipments.py]"]
  node_reminder_worker["Reminder worker<br/>[reminder_worker.py]"]
end

subgraph group_persistence["Persistence"]
  node_shipment_repo["Shipment and reminder repositories<br/>[repository.py]"]
  node_database[("SQLite database and migrations<br/>[db.py]")]
  node_sessions[("Workspace sessions<br/>[sessions.py]")]
end

subgraph group_domain["Domain and formatting"]
  node_ui_format["Workspace rendering<br/>[format.py]"]
  node_status["Shipment statuses<br/>[status.py]"]
  node_countries["Country helpers<br/>[countries.py]"]
  node_date_utils["Date and timezone helpers<br/>[dates.py]"]
  node_text_format["Formatting helpers<br/>[formatting.py]"]
end

node_operator(("Authorized user"))
node_telegram(("Telegram"))

node_operator -->|"uses bot"| node_telegram
node_telegram -->|"sends updates"| node_auth
node_auth -->|"routes authorized"| node_workspace_handler
node_bot -->|"registers middleware"| node_auth
node_bot -->|"registers handlers"| node_workspace_handler
node_bot -->|"connects database"| node_database
node_bot -->|"creates repositories"| node_shipment_repo
node_bot -->|"creates sessions"| node_sessions
node_bot -->|"starts worker"| node_reminder_worker
node_workspace_handler -->|"coordinates workspace"| node_workspace_engine
node_workspace_handler -->|"requests views"| node_views
node_workspace_handler -->|"reads and edits"| node_shipment_repo
node_workspace_handler -->|"stores workspace state"| node_sessions
node_views -->|"loads shipment data"| node_shipment_repo
node_views -->|"builds controls"| node_ui_keyboards
node_views -->|"formats screens"| node_ui_format
node_ui_keyboards -->|"uses status options"| node_status
node_ui_format -->|"labels statuses"| node_status
node_ui_format -->|"formats countries"| node_countries
node_ui_format -->|"formats dates"| node_date_utils
node_legacy_handlers -->|"manages shipments"| node_shipment_repo
node_legacy_handlers -->|"formats responses"| node_text_format
node_shipment_repo -->|"queries and writes"| node_database
node_reminder_worker -->|"loads due reminders"| node_shipment_repo
node_reminder_worker -->|"delivers reminders"| node_telegram

click node_bot "https://github.com/mikemin32/shipmentstrackbot/blob/main/bot.py"
click node_auth "https://github.com/mikemin32/shipmentstrackbot/blob/main/middlewares/auth.py"
click node_workspace_handler "https://github.com/mikemin32/shipmentstrackbot/blob/main/handlers/workspace.py"
click node_legacy_handlers "https://github.com/mikemin32/shipmentstrackbot/blob/main/handlers/shipments.py"
click node_workspace_engine "https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/workspace.py"
click node_views "https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/views.py"
click node_ui_keyboards "https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/keyboards.py"
click node_ui_format "https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/format.py"
click node_status "https://github.com/mikemin32/shipmentstrackbot/blob/main/domain/status.py"
click node_countries "https://github.com/mikemin32/shipmentstrackbot/blob/main/domain/countries.py"
click node_date_utils "https://github.com/mikemin32/shipmentstrackbot/blob/main/utils/dates.py"
click node_text_format "https://github.com/mikemin32/shipmentstrackbot/blob/main/utils/formatting.py"
click node_shipment_repo "https://github.com/mikemin32/shipmentstrackbot/blob/main/database/repository.py"
click node_database "https://github.com/mikemin32/shipmentstrackbot/blob/main/database/db.py"
click node_sessions "https://github.com/mikemin32/shipmentstrackbot/blob/main/database/sessions.py"
click node_reminder_worker "https://github.com/mikemin32/shipmentstrackbot/blob/main/services/reminder_worker.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_auth,node_operator toneBlue
class node_workspace_handler,node_workspace_engine,node_views,node_ui_keyboards toneAmber
class node_legacy_handlers,node_reminder_worker toneMint
class node_shipment_repo,node_database,node_sessions toneRose
class node_ui_format,node_status,node_countries,node_date_utils,node_text_format,node_telegram toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot.py): `bot.py`
- [Allowlist middleware](https://github.com/mikemin32/shipmentstrackbot/blob/main/middlewares/auth.py): `middlewares/auth.py`

### Interactive workspace

- [Workspace handlers](https://github.com/mikemin32/shipmentstrackbot/blob/main/handlers/workspace.py): `handlers/workspace.py`
- [Workspace state and navigation](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/workspace.py): `bot_ui/workspace.py`
- [Workspace views](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/views.py): `bot_ui/views.py`
- [Workspace keyboards](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/keyboards.py): `bot_ui/keyboards.py`

### Shipment operations

- [Command and shipment handlers](https://github.com/mikemin32/shipmentstrackbot/blob/main/handlers/shipments.py): `handlers/shipments.py`
- [Reminder worker](https://github.com/mikemin32/shipmentstrackbot/blob/main/services/reminder_worker.py): `services/reminder_worker.py`

### Persistence

- [Shipment and reminder repositories](https://github.com/mikemin32/shipmentstrackbot/blob/main/database/repository.py): `database/repository.py`
- [SQLite database and migrations](https://github.com/mikemin32/shipmentstrackbot/blob/main/database/db.py): `database/db.py`
- [Workspace sessions](https://github.com/mikemin32/shipmentstrackbot/blob/main/database/sessions.py): `database/sessions.py`

### Domain and formatting

- [Workspace rendering](https://github.com/mikemin32/shipmentstrackbot/blob/main/bot_ui/format.py): `bot_ui/format.py`
- [Shipment statuses](https://github.com/mikemin32/shipmentstrackbot/blob/main/domain/status.py): `domain/status.py`
- [Country helpers](https://github.com/mikemin32/shipmentstrackbot/blob/main/domain/countries.py): `domain/countries.py`
- [Date and timezone helpers](https://github.com/mikemin32/shipmentstrackbot/blob/main/utils/dates.py): `utils/dates.py`
- [Formatting helpers](https://github.com/mikemin32/shipmentstrackbot/blob/main/utils/formatting.py): `utils/formatting.py`

### Other components

- **Authorized user**
- **Telegram**

## Connections

- Authorized user → Telegram: uses bot (evidence: `README.md`)
- Telegram → Allowlist middleware: sends updates (evidence: `README.md`)
- Allowlist middleware → Workspace handlers: routes authorized (evidence: `README.md`)
- Bot startup → Allowlist middleware: registers middleware (evidence: `bot.py`)
- Bot startup → Workspace handlers: registers handlers
- Bot startup → SQLite database and migrations: connects database (evidence: `bot.py`)
- Bot startup → Shipment and reminder repositories: creates repositories (evidence: `bot.py`)
- Bot startup → Workspace sessions: creates sessions (evidence: `bot.py`)
- Bot startup → Reminder worker: starts worker (evidence: `bot.py`)
- Workspace handlers → Workspace state and navigation: coordinates workspace (evidence: `handlers/workspace.py`)
- Workspace handlers → Workspace views: requests views (evidence: `handlers/workspace.py`)
- Workspace handlers → Shipment and reminder repositories: reads and edits (evidence: `handlers/workspace.py`)
- Workspace handlers → Workspace sessions: stores workspace state (evidence: `handlers/workspace.py`)
- Workspace views → Shipment and reminder repositories: loads shipment data (evidence: `bot_ui/views.py`)
- Workspace views → Workspace keyboards: builds controls (evidence: `bot_ui/views.py`)
- Workspace views → Workspace rendering: formats screens (evidence: `bot_ui/views.py`)
- Workspace keyboards → Shipment statuses: uses status options (evidence: `bot_ui/keyboards.py`)
- Workspace rendering → Shipment statuses: labels statuses (evidence: `bot_ui/format.py`)
- Workspace rendering → Country helpers: formats countries (evidence: `bot_ui/format.py`)
- Workspace rendering → Date and timezone helpers: formats dates (evidence: `bot_ui/format.py`)
- Command and shipment handlers → Shipment and reminder repositories: manages shipments (evidence: `handlers/shipments.py`)
- Command and shipment handlers → Formatting helpers: formats responses (evidence: `handlers/shipments.py`)
- Shipment and reminder repositories → SQLite database and migrations: queries and writes (evidence: `database/repository.py`)
- Reminder worker → Shipment and reminder repositories: loads due reminders (evidence: `services/reminder_worker.py`)
- Reminder worker → Telegram: delivers reminders (evidence: `README.md`)
