# intensy/aiogram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/intensy/aiogram-bot
- Repository: https://github.com/intensy/aiogram-bot

## Overview

##### Project Type and Purpose
- The project is a Telegram chatbot designed to provide users with an electronic version of books stored in a database (or optionally an object storage like S3).
- It is built using Python (3.11+), aiogram (Telegram framework), PostgreSQL as the database, Docker for containerization, and follows clean architecture principles for maintainability and scalability.

##### Analyzing the File Structure
- Top-level files like Dockerfile, .env.example, and docker-compose files indicate that containerization and deployment configurations are taken care of.
- The project is organized into several layers, as typical in clean architecture:
- Presentation: Located under src/presentation (entrypoint, routers for books and commands).
- Application: Under src/applications containing use_cases (for books and commands), interfaces (for core interactions like transaction management, logging, mapping), and contracts.
- Domain: Under src/domain, which houses the business logic components (entities and repositories for accounts, books, and core value objects).
- Infrastructure: Under src/infrastructure, subdivided into DI (dependency injection), persistence (models, repositories, migrations, transactions), services (internal and external), and settings.
- Other supporting directories include logs, books (which hosts sample PDFs), and configuration files like alembic.ini for database migration.

a. Main Components to Include:
- Telegram Client/Users: Representing the external users interacting via the Telegram app.
- Presentation Layer:
- Components: Entry point (src/presentation/entrypoint.py) and routers (src/presentation/routers/*)
- Role: Handles incoming messages/commands from Telegram.
- Application Layer:
- Components: Contracts, use cases (books and commands), and interfaces (for interactor, logger, mapper, transaction manager).
- Role: Orchestrates application logic by receiving input from the presentation layer and processing it using domain logic.
- Domain Layer:
- Components: Entities and repositories for books and accounts housed in src/domain.
- Role: Contains business rules and domain logic independent of any frameworks or external concerns.
- Infrastructure Layer:
- Components: Dependency Injection configuration (di), Persistence (database models, mappers, repositories, migrations, transactions), Services (internal for logger, keyboards; external integrations), and Settings.
- Role: Provides actual implementations for persistence, configuration, and external communications.
- Database & External Services:
- PostgreSQL: Acts as the primary storage.
- (Optional) Object storage like S3 for storing book files.
- Telegram API: Part of the external world.
- Docker & Deployment:
- Docker-compose and Dockerfile indicate the containerized environment that encapsulates these layers for deployment.

b. Relationships and Interactions:
- Incoming user commands from Telegram are received by the Presentation Layer.
- The Presentation Layer routes requests to corresponding Use Cases in the Application Layer.
- The Use Cases invoke Domain Layer entities and operations to process business logic.
- The Domain Layer communicates with the persistence mechanisms in the Infrastructure Layer through repositories.
- Infrastructure services (like logging, keyboards for user response interfaces) support additional functionality.
- All these interactions are mediated through dependency injection (shown in the DI component) and contracts/interfaces ensuring loose coupling.

##### Architectural Patterns & Design Principles
- Dependency Inversion: Emphasize how the Application and Domain layers remain independent and how Infrastructure provides implementations.
- Containerization: Illustrate Docker’s role in encapsulating the full environment including DB migrations (via Alembic) and service orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    subgraph "External"
        extUser["Telegram Client/Users"]:::external
        extAPI["Telegram API"]:::external
    end

    %% Docker & Deployment Components
    subgraph "Docker & Deployment"
        dockerA["Dockerfile"]:::docker
        dockerC["Docker Compose"]:::docker
        envConfig["Env Config"]:::docker
        alembic["Alembic Config"]:::docker
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        pEntrypoint["Entry Point"]:::presentation
        pRouters["Routers"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        appUse["Use Cases"]:::application
        appContracts["Contracts"]:::application
        appInterfaces["Interfaces"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        domainBiz["Business Entities & Repositories"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        infraDI["Dependency Injection"]:::infrastructure
        infraPersistence["Persistence"]:::infrastructure
        infraServices["Services"]:::infrastructure
        infraSettings["Settings"]:::infrastructure
    end

    %% External Databases & Storage
    subgraph "External Databases & Storage"
        db["PostgreSQL DB"]:::db
        storage["Object Storage (S3)"]:::external
    end

    %% Persistence Details within Infrastructure
    subgraph "Persistence Details"
        models["Models"]:::infrastructure
        mappers["Mappers"]:::infrastructure
        repositories["Repositories"]:::infrastructure
        migrations["Migrations & Transactions"]:::infrastructure
    end

    %% Service Details within Infrastructure
    subgraph "Services Details"
        servicesInternal["Internal Services"]:::infrastructure
        servicesExternal["External Services"]:::infrastructure
    end

    %% Books Storage
    subgraph "Books Storage"
        booksStorage["Sample PDFs"]:::external
    end

    %% Arrows: External to Presentation
    extUser -->|"sendsCommand"| pEntrypoint
    extAPI -.->|"communicates"| pEntrypoint

    %% Arrows: Presentation to Application
    pEntrypoint -->|"routesMessage"| pRouters
    pRouters -->|"invokes"| appUse
    pRouters -->|"usesContractsInterfaces"| appContracts
    appContracts -->|"definesInterfaces"| appInterfaces
    appInterfaces -->|"supports"| appUse

    %% Arrows: Application to Domain
    appUse -->|"executesBusinessLogic"| domainBiz

    %% Arrows: Domain to Infrastructure
    domainBiz -->|"callsPersistence"| infraPersistence

    %% Dependency Injection & Service Support
    infraDI -->|"injectsTo"| appUse
    infraDI -->|"injectsTo"| domainBiz
    infraServices -->|"supports"| appUse
    infraServices -->|"supports"| domainBiz

    %% Infrastructure External Connections
    infraPersistence -->|"dbOperations"| db
    infraServices -->|"accessFiles"| storage

    %% Docker & Deployment connected to Presentation & Infrastructure
    dockerA --- pEntrypoint
    dockerC --- pEntrypoint
    envConfig --- pEntrypoint
    alembic --- infraPersistence

    %% Persistence Layer internal breakdown
    infraPersistence --> models
    infraPersistence --> mappers
    infraPersistence --> repositories
    infraPersistence --> migrations

    %% Services Layer internal breakdown
    infraServices --> servicesInternal
    infraServices --> servicesExternal

    %% Books Storage connected to Infrastructure Services
    booksStorage --- infraServices

    %% Click Events for Docker & Deployment
    click dockerA "https://github.com/intensy/aiogram-bot/tree/master/Dockerfile"
    click dockerC "https://github.com/intensy/aiogram-bot/blob/master/docker/docker-compose.yml"
    click envConfig "https://github.com/intensy/aiogram-bot/blob/master/.env.example"
    click alembic "https://github.com/intensy/aiogram-bot/blob/master/alembic.ini"

    %% Click Events for Presentation Layer
    click pEntrypoint "https://github.com/intensy/aiogram-bot/blob/master/src/presentation/entrypoint.py"
    click pRouters "https://github.com/intensy/aiogram-bot/tree/master/src/presentation/routers"

    %% Click Events for Application Layer
    click appUse "https://github.com/intensy/aiogram-bot/tree/master/src/applications/use_cases"
    click appContracts "https://github.com/intensy/aiogram-bot/tree/master/src/applications/contracts"
    click appInterfaces "https://github.com/intensy/aiogram-bot/tree/master/src/applications/interfaces"

    %% Click Event for Domain Layer
    click domainBiz "https://github.com/intensy/aiogram-bot/tree/master/src/domain"

    %% Click Events for Infrastructure Layer
    click infraDI "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/di"
    click infraPersistence "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/persistence/models"
    click models "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/persistence/models"
    click mappers "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/persistence/mappers"
    click repositories "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/persistence/repositories"
    click migrations "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/persistence/migrations"
    click servicesInternal "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/services/internal"
    click servicesExternal "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/services/external"
    click infraSettings "https://github.com/intensy/aiogram-bot/tree/master/src/infrastructure/settings"
    
    %% Click Event for Books Storage
    click booksStorage "https://github.com/intensy/aiogram-bot/tree/master/books"

    %% Style Definitions
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef docker fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef presentation fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef application fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef domain fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef db fill:#98FB98,stroke:#000,stroke-width:2px;
```
