# ram333n/tg-bot-personal-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ram333n/tg-bot-personal-assistant
- Repository: https://github.com/ram333n/tg-bot-personal-assistant

## Overview

Proko is a Telegram personal-assistant bot. Users interact through stateful conversations: incoming updates are handled according to session state, then feature services produce replies or persist/schedule work. The README documents translation, QR generation, notes, reminders (manual and AI-assisted), and weather. The excerpts show service-to-repository scheduling and session persistence, but not the bot’s dispatch wiring or most feature handlers; those connections are therefore marked unverified where needed.

Main entry points: [`tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl`](https://github.com/ram333n/tg-bot-personal-assistant/tree/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl) (Conversation handlers), [`tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java`](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java) (Reminder scheduling), [`tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/bot/CustomTelegramLongPollingBot.java`](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/bot/CustomTelegramLongPollingBot.java) (Long-polling bot), [`tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl/DefaultDispatcherHandler.java`](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl/DefaultDispatcherHandler.java) (Request dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Telegram conversations"]
  node_bot["Long-polling bot"]
  node_dispatcher["Request dispatcher"]
  node_handlers["Conversation handlers"]
  node_session["Conversation state"]
  node_sender["Message sender"]
end

subgraph group_features["Assistant features"]
  node_notes["Notes management"]
  node_notifications["Reminder scheduling"]
  node_ai["AI assistance"]
  node_qr["QR generation"]
  node_weather["Weather forecast"]
  node_translation["Text translation"]
end

subgraph group_persistence["Persistence and scheduling"]
  node_sessiondb[("Session store")]
  node_notedb[("Notes store")]
  node_notificationdb[("Reminder store")]
end

subgraph group_integrations["External integrations"]
  node_telegram{{"Telegram platform"}}
  node_jobrunr["Job scheduler"]
  node_weatherapi{{"OpenWeatherMap"}}
end

node_user(("Telegram user"))

node_user -->|"sends updates"| node_telegram
node_telegram -.->|"delivers updates"| node_bot
node_bot -.->|"routes updates"| node_dispatcher
node_dispatcher -.->|"dispatches by state"| node_handlers
node_handlers -.->|"reads and updates"| node_session
node_session -->|"reads and writes"| node_sessiondb
node_handlers -.->|"manages notes"| node_notes
node_notes -->|"reads and writes"| node_notedb
node_handlers -.->|"manages reminders"| node_notifications
node_notifications -->|"reads and writes"| node_notificationdb
node_notifications -->|"schedules jobs"| node_jobrunr
node_notifications -.->|"sends due reminders"| node_sender
node_handlers -.->|"requests suggestions"| node_ai
node_ai -.->|"suggests reminders"| node_notifications
node_handlers -.->|"requests QR image"| node_qr
node_handlers -.->|"requests forecast"| node_weather
node_weather -->|"fetches current weather"| node_weatherapi
node_handlers -.->|"requests translation"| node_translation
node_sender -.->|"sends replies"| node_telegram

click node_bot "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/bot/CustomTelegramLongPollingBot.java"
click node_dispatcher "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl/DefaultDispatcherHandler.java"
click node_handlers "https://github.com/ram333n/tg-bot-personal-assistant/tree/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl"
click node_session "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/service/impl/DefaultUserSessionService.java"
click node_sessiondb "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/repository/UserSessionRepository.java"
click node_sender "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/sender/impl/DefaultSenderService.java"
click node_notes "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/service/impl/DefaultNoteService.java"
click node_notedb "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/repository/NoteRepository.java"
click node_notifications "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java"
click node_notificationdb "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/repository/NotificationRepository.java"
click node_ai "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai/impl/DefaultAiService.java"
click node_qr "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/qr/impl/DefaultQrService.java"
click node_weather "https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/weather/impl/DefaultWeatherService.java"
click node_translation "https://github.com/ram333n/tg-bot-personal-assistant/tree/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai"

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_dispatcher,node_handlers,node_session,node_sender,node_user toneBlue
class node_notes,node_notifications,node_ai,node_qr,node_weather,node_translation toneAmber
class node_sessiondb,node_notedb,node_notificationdb toneMint
class node_telegram,node_jobrunr,node_weatherapi toneRose
```

## Components

### Telegram conversations

- [Long-polling bot](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/bot/CustomTelegramLongPollingBot.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/bot/CustomTelegramLongPollingBot.java`
- [Request dispatcher](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl/DefaultDispatcherHandler.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl/DefaultDispatcherHandler.java`
- [Conversation handlers](https://github.com/ram333n/tg-bot-personal-assistant/tree/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/handler/impl`
- [Conversation state](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/service/impl/DefaultUserSessionService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/service/impl/DefaultUserSessionService.java`
- [Message sender](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/sender/impl/DefaultSenderService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/sender/impl/DefaultSenderService.java`

### Assistant features

- [Notes management](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/service/impl/DefaultNoteService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/service/impl/DefaultNoteService.java`
- [Reminder scheduling](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java`
- [AI assistance](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai/impl/DefaultAiService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai/impl/DefaultAiService.java`
- [QR generation](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/qr/impl/DefaultQrService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/qr/impl/DefaultQrService.java`
- [Weather forecast](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/weather/impl/DefaultWeatherService.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/weather/impl/DefaultWeatherService.java`
- [Text translation](https://github.com/ram333n/tg-bot-personal-assistant/tree/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/ai`

### Persistence and scheduling

- [Session store](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/repository/UserSessionRepository.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/repository/UserSessionRepository.java`
- [Notes store](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/repository/NoteRepository.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/repository/NoteRepository.java`
- [Reminder store](https://github.com/ram333n/tg-bot-personal-assistant/blob/main/tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/repository/NotificationRepository.java): `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/repository/NotificationRepository.java`

### External integrations

- **Telegram platform**
- **Job scheduler**
- **OpenWeatherMap**

### Other components

- **Telegram user**

## Connections

- Telegram user → Telegram platform: sends updates (evidence: `README.md`)
- Telegram platform → Long-polling bot: delivers updates
- Long-polling bot → Request dispatcher: routes updates
- Request dispatcher → Conversation handlers: dispatches by state
- Conversation handlers → Conversation state: reads and updates
- Conversation state → Session store: reads and writes (evidence: `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/session/service/impl/DefaultUserSessionService.java`)
- Conversation handlers → Notes management: manages notes
- Notes management → Notes store: reads and writes (evidence: `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notes/service/impl/DefaultNoteService.java`)
- Conversation handlers → Reminder scheduling: manages reminders
- Reminder scheduling → Reminder store: reads and writes (evidence: `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java`)
- Reminder scheduling → Job scheduler: schedules jobs (evidence: `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/notification/service/impl/DefaultNotificationService.java`)
- Reminder scheduling → Message sender: sends due reminders
- Conversation handlers → AI assistance: requests suggestions
- AI assistance → Reminder scheduling: suggests reminders
- Conversation handlers → QR generation: requests QR image
- Conversation handlers → Weather forecast: requests forecast
- Weather forecast → OpenWeatherMap: fetches current weather (evidence: `tg-bot-personal-assistant/src/main/java/com/prokopchuk/tgbotpersonalassistant/weather/impl/DefaultWeatherService.java`)
- Conversation handlers → Text translation: requests translation
- Message sender → Telegram platform: sends replies
