# itamarco/telegram-heb-dates-reminder architecture

> Architecture diagram of the GitHub repository itamarco/telegram-heb-dates-reminder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itamarco/telegram-heb-dates-reminder
- Repository: https://github.com/itamarco/telegram-heb-dates-reminder

## Overview

##### Main Components

a) Client Layer:
- Telegram Platform (external service)
- User Interface (Telegram Bot interface)

b) Application Core:
- Bot Service Layer (app/bot/*)
- User Flow Handler (app/user_flow.py)
- Operations Handler (app/operations.py)
- Route Handler (app/routes.py)

c) Supporting Services:
- Cron Job Service (separate container)
- Database Layer (app/db.py)

d) Utility Components:
- Date Utils (app/date_utils.py)
- Text Patterns (app/text_patterns.py)
- Custom Logger (app/custom_logger.py)

**[Telegram Platform] <---> [Bot Service Layer]**

- v
**[User Interface] <---> [Route Handler] <---> [User Flow Handler]**

- v
- [Operations Handler]

- v
**[Cron Service] <---------------> [Database Layer] <---> [Date Utils]**

##### Special Elements to Highlight

- Model layer (app/models/*) showing the data structures
- Environment configuration (.env)
- API endpoints (vercel.json)
- Testing coverage (tests/*)

##### Implementation Details

- Asynchronous nature of bot communications
- Separation between bot implementation and business logic
- Date conversion and handling utilities
- Database operations and state management

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        TP[Telegram Platform]:::external
        UI[Telegram Bot Interface]:::interface
        click UI "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/bot/telegram_bot.py"
    end

    subgraph "Application Core"
        subgraph "Bot Layer"
            BS[Bot Service]:::service
            BI[Bot Implementation]:::service
            click BS "https://github.com/itamarco/telegram-heb-dates-reminder/tree/master/app/bot/"
            click BI "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/bot/bot_impl.py"
        end

        subgraph "Handler Layer"
            RH[Route Handler]:::handler
            UF[User Flow Handler]:::handler
            OH[Operations Handler]:::handler
            click RH "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/routes.py"
            click UF "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/user_flow.py"
            click OH "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/operations.py"
        end

        subgraph "Data Layer"
            DB[(Database)]:::database
            click DB "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/db.py"
        end

        subgraph "Models"
            RM[Reminder Model]:::model
            CM[Context Model]:::model
            BRM[Bot Response Model]:::model
            click RM "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/models/reminder.py"
            click CM "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/models/context.py"
            click BRM "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/models/bot_response.py"
        end
    end

    subgraph "Support Services"
        CS[Cron Service]:::service
        DU[Date Utils]:::util
        TP_P[Text Patterns]:::util
        CL[Custom Logger]:::util
        click CS "https://github.com/itamarco/telegram-heb-dates-reminder/tree/master/cron/"
        click DU "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/date_utils.py"
        click TP_P "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/text_patterns.py"
        click CL "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/app/custom_logger.py"
    end

    subgraph "Configuration"
        ENV[Environment Config]:::config
        API[API Config]:::config
        DC[Docker Config]:::config
        click ENV "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/.env"
        click API "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/vercel.json"
        click DC "https://github.com/itamarco/telegram-heb-dates-reminder/blob/master/docker-compose.yml"
    end

    subgraph "Testing"
        TS[Test Suite]:::test
        click TS "https://github.com/itamarco/telegram-heb-dates-reminder/tree/master/tests/"
    end

    %% Relationships
    TP <--> UI
    UI --> BS
    BS --> BI
    BI --> RH
    RH --> UF
    UF --> OH
    OH --> DB
    DB <--> CS
    
    %% Model Relationships
    OH --> RM
    OH --> CM
    OH --> BRM
    
    %% Utility Relationships
    OH --> DU
    OH --> TP_P
    BS --> CL
    
    %% Configuration Relationships
    ENV -.-> BS
    API -.-> RH
    DC -.-> CS
    
    %% Testing Relationships
    TS -.-> BS
    TS -.-> OH
    TS -.-> DB

    %% Styling
    classDef external fill:#B2DFEE
    classDef interface fill:#98FB98
    classDef service fill:#90EE90
    classDef handler fill:#3CB371
    classDef database fill:#F0E68C
    classDef model fill:#DDA0DD
    classDef util fill:#D3D3D3
    classDef config fill:#FFB6C1
    classDef test fill:#FFA07A
```
