# anoldyouth/java-telegram-notifications architecture

> Architecture diagram of the GitHub repository anoldyouth/java-telegram-notifications, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anoldyouth/java-telegram-notifications
- Repository: https://github.com/anoldyouth/java-telegram-notifications

## Overview

##### Main Components
- Bot Application:
- Located under the “bot” module.
- Contains Spring Boot configuration (ApplicationConfig, BotConfiguration, ScenariosConfiguration).
- Implements various command actions (StartAction, HelpAction, etc.), a dispatcher for scenarios, and response classes that produce Telegram messages.
- Contains unit and integration tests, ensuring proper behavior.
- Scrapper Application:
- Located under the “scrapper” module.
- Contains application configuration classes and client integrations for external APIs (GitHubClient for GitHub and StackOverflowClient for StackOverflow).
- Implements a scheduler service (LinkUpdaterScheduler) to periodically fetch and update link data.
- Uses DTOs for requests and responses that map to external API data.
- Database (PostgreSQL):
- The README mentions a required PostgreSQL database which acts as a storage layer for link tracking data or for caching events.
- Optional Kafka:
- There is a dependency note on Kafka. If enabled, Kafka can serve as a messaging bus, for instance, between the scrapper and bot components, to relay update events asynchronously.
- External Systems:
- Telegram: for sending notifications from the Bot application.
- GitHub and StackOverflow APIs: called by the Scrapper application to monitor link events.

##### Relationships and Interactions
- The Scrapper periodically calls external APIs (GitHub and StackOverflow) to fetch updates based on the configured links.
- Upon detecting a new event/update, the Scrapper may update the PostgreSQL database and, optionally, publish events on Kafka.
- The Bot application, which likely monitors updates (either directly by polling the database or by consuming Kafka messages), processes incoming commands (via the various Action classes) and sends notification responses to Telegram.
- There is an integration between the two applications either through shared database state or messaging, enabling coordinated operations in tracking and alerting.

##### Architectural Patterns and Design Principles
- Modular Architecture:
- Both subsystems (Bot and Scrapper) are built as independent Spring Boot modules, each with well-defined responsibilities.
- Separation of Concerns:
- Configuration, service, client integration, and utility logic are neatly separated.
- Use of Scheduler (in Scrapper) for periodic tasks.
- Strong emphasis on event-based operation (using Kafka optionally) for decoupled communication if needed.
- MVC-like structure inside each module (with controllers/services, even if not strictly MVC in the code structure).
- Extensive unit testing supports reliability and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bot Application Subgraph
    subgraph "Bot Application"
        BOT_MAIN["Bot: Main Module"]:::application
        BOT_CONFIG["Bot: Spring Boot Config"]:::configuration
        BOT_DISPATCHER["Bot: Scenario Dispatcher"]:::action
        BOT_ACTION["Bot: Command Actions"]:::action
        BOT_RESPONSE["Bot: Response Generation"]:::response
    end

    %% Scrapper Application Subgraph
    subgraph "Scrapper Application"
        SCRAPPER_MAIN["Scrapper: Main Module"]:::application
        SCRAPPER_SCHEDULER["Scrapper: Scheduler (LinkUpdater)"]:::scheduler
        SCRAPPER_GITHUB["Scrapper: GitHub Client"]:::client
        SCRAPPER_STACK["Scrapper: StackOverflow Client"]:::client
    end

    %% External and Database Components
    DB["PostgreSQL Database"]:::database
    KAFKA["Kafka Messaging Bus"]:::mq
    TELEGRAM["Telegram Notifications"]:::external
    GITHUB_API["GitHub API"]:::external
    STACK_API["StackOverflow API"]:::external

    %% Bot internal flows
    BOT_MAIN --> BOT_CONFIG
    BOT_CONFIG --> BOT_DISPATCHER
    BOT_DISPATCHER --> BOT_ACTION
    BOT_ACTION --> BOT_RESPONSE
    BOT_RESPONSE -->|"sends"| TELEGRAM

    %% Bot consumes updates
    BOT_MAIN -->|"polls"| DB
    KAFKA -->|"consumed by"| BOT_MAIN

    %% Scrapper flows
    SCRAPPER_MAIN --> SCRAPPER_SCHEDULER
    SCRAPPER_SCHEDULER -->|"calls"| SCRAPPER_GITHUB
    SCRAPPER_GITHUB -->|"fetches"| GITHUB_API
    SCRAPPER_SCHEDULER -->|"calls"| SCRAPPER_STACK
    SCRAPPER_STACK -->|"fetches"| STACK_API
    SCRAPPER_SCHEDULER -->|"updates"| DB
    SCRAPPER_SCHEDULER -->|"publishes"| KAFKA

    %% Click Events
    click BOT_MAIN "https://github.com/anoldyouth/java-telegram-notifications/tree/main/bot/"
    click BOT_CONFIG "https://github.com/anoldyouth/java-telegram-notifications/tree/main/bot/src/main/java/edu/java/bot/configuration/"
    click BOT_DISPATCHER "https://github.com/anoldyouth/java-telegram-notifications/blob/main/bot/src/main/java/edu/java/bot/util/ScenarioDispatcher.java"
    click BOT_ACTION "https://github.com/anoldyouth/java-telegram-notifications/tree/main/bot/src/main/java/edu/java/bot/util/action/"
    click BOT_RESPONSE "https://github.com/anoldyouth/java-telegram-notifications/tree/main/bot/src/main/java/edu/java/bot/util/response/"
    click SCRAPPER_MAIN "https://github.com/anoldyouth/java-telegram-notifications/tree/main/scrapper/"
    click SCRAPPER_GITHUB "https://github.com/anoldyouth/java-telegram-notifications/blob/main/scrapper/src/main/java/edu/java/client/github/GitHubClient.java"
    click SCRAPPER_STACK "https://github.com/anoldyouth/java-telegram-notifications/blob/main/scrapper/src/main/java/edu/java/client/stackoverflow/StackOverflowClient.java"
    click SCRAPPER_SCHEDULER "https://github.com/anoldyouth/java-telegram-notifications/blob/main/scrapper/src/main/java/edu/java/service/LinkUpdaterScheduler.java"

    %% Styles
    classDef application fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef configuration fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef action fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef response fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef scheduler fill:#FFE082,stroke:#FF6F00,stroke-width:2px;
    classDef client fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef database fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef mq fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef external fill:#D7CCC8,stroke:#4E342E,stroke-width:2px;
```
