# abdulbositabdurahimovdeveloper/kundalik architecture

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

- Interactive diagram: https://gitdiagram.com/abdulbositabdurahimovdeveloper/kundalik
- Repository: https://github.com/abdulbositabdurahimovdeveloper/kundalik

## Overview

##### Project Type & Purpose
- KUNDALIK is a modular monolithic, full-stack Java Spring Boot application that exposes a REST API (“site” module) and a Telegram Bot interface (“telegram” module).
- Purpose: A multi-platform personal assistant offering weather, prayer-time, currency info to anonymous users; note/reminder/finance management for authenticated users; and a Telegram bot front-end.

##### File Structure
- Top-level build & infra: Dockerfile, Jenkinsfile, Maven wrapper & `pom.xml`.
- Single Spring Boot application in `src/main/java/uz/kundalik`, split into two logical sub-packages:
- `site` – the REST API (controllers, services, repositories, config, models, mappers, payloads).
- `telegram` – the bot logic (webhook controllers, bot controllers, services, repositories, mappers, payloads).
- Configuration & cross-cutting concerns under `site/config` (security, caching, async, logging, OpenAPI).
- Resources: Liquibase changelogs (`db/changelog`), static front-end assets (admin-panel, guide, i18n, mini-app), email and page templates.
- Tests under `src/test`.

##### Key Insights from README
- Tech stack: Java17, Spring Boot 3, Spring Data JPA (PostgreSQL), Liquibase, Spring Security + JWT, Redis cache, MinIO storage, TelegramBots library, OpenAPI, Lombok & MapStruct, cron-utils.
- Modular design: `site` (REST API), `telegram` (bot).
- External dependencies: currency, weather, prayer-time APIs; Redis; MinIO; PostgreSQL.

##### Main Components & Their Interactions

A. Clients / Entry Points
1. Web clients (static admin-panel & mini-app in `src/main/resources/static`)
2. API consumers (Swagger UI / any HTTP client)
3. Telegram platform (user’s Telegram app → Bot via Webhook)

B. API / Gateway Layer
- Spring MVC Dispatcher (controllers in `site/controller` & `telegram/controller`)
- JWT Authentication Filter (`JwtAuthenticationFilter`) & SecurityConfig
- OpenAPI endpoint

C. Business Logic Layer
- Site services (`site/service` implementations & interfaces)
- Telegram services (message generation, panel handling, keyboard builders, API clients)

D. Data Access Layer
- Spring Data JPA Repositories
- Liquibase migrations applied on startup
- Soft-deletion entities

E. Infrastructure & Supporting Services
- PostgreSQL Database
- Redis Cache (Spring Cache)
- MinIO Object Storage
- External REST API clients: WeatherApiClient, CurrencyApiClient, PrayerTimeApiClient
- MailService (SMTP) & SmsService (Telegram or other SMS gateway)
- Asynchronous executor thread pool (AsyncConfig) & cron-utils scheduler

##### Relationships & Data Flows
- HTTP/webhook → API Gateway → Controllers → Services → Repositories → Database / Cache / MinIO
- Services may call external REST APIs or send email/SMS → back to users
- Telegram updates flow from Telegram Platform (via webhook) into `TelegramWebhookController`, pass through `UpdateDispatcherService` → appropriate bot-panel services → send messages via `SendMsg` to Telegram Platform
- Admin-panel web UI communicates with REST endpoints (secured via JWT)

##### Architectural Patterns & Design Principles
- Modular monolith (two main logical modules, but one deployable JAR)
- Layered architecture: Controller → Service → Repository → Model
- Event publishing (e.g., `UserRegisteredEvent`) for decoupling
- Soft deletion & auditing via base entities (`AbsAuditingSoftDeleteEntity`)
- Externalization of config (`application.yaml`, `ApplicationProperties` classes, `spring-dotenv`)
- Mapping layer (MapStruct) to translate Entities ↔ DTOs
- Validation via custom annotations & global exception handler

##### Essential Elements to Capture
- Modules: Site vs. Telegram
- Layers inside each: Controller → Service → Repository
- Cross-cutting: Security, Caching, Async
- External integrations: MinIO, Redis, PostgreSQL, Weather/Currency/Prayer APIs, Email/SMS, Telegram Platform
- Startup flows: Liquibase migrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients / Entry Points
    subgraph "Clients" 
        direction TB
        AdminUI["Web Client (Admin UI)"]:::client
        MiniApp["Mini-app Client (Telegram UI)"]:::client
        Guide["User Guide Front-end"]:::client
        I18n["Internationalization Front-end"]:::client
        SwaggerUI["OpenAPI/Swagger Endpoint"]:::client
        TelegramPlatform["Telegram Platform"]:::external
    end

    %% Application Boundary
    subgraph "KUNDALIK Application" 
        direction TB

        %% API / Gateway Layer
        subgraph "API / Gateway Layer"
            direction TB
            JwtFilter["JWT Authentication Filter"]:::security
            SecurityCfg["Security Configuration"]:::security
            DispatcherSite["Spring MVC Dispatcher – Site"]:::module
            DispatcherTelegram["Spring MVC Dispatcher – Telegram"]:::module
            OpenAPI["OpenAPI Endpoint"]:::module
        end

        %% Business Logic Layer
        subgraph "Business Logic Layer"
            direction TB
            SiteServices["Site Services"]:::module
            TelegramServices["Telegram Services"]:::module
        end

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            SiteRepos["Site Repositories"]:::module
            TelegramRepos["Telegram Repositories"]:::module
            SiteEntities["Site Entities"]:::module
            TelegramEntities["Telegram Entities"]:::module
        end

        %% Infrastructure & Supporting Services
        subgraph "Infra & Supporting"
            direction TB
            Liquibase["Liquibase Migrations"]:::config
            AsyncCfg["Asynchronous Executor Config"]:::config
            CacheCfg["Cache Configuration (Redis)"]:::config
            MinioSvc["MinIO Storage Service"]:::module
            MailSvc["Mail Service (SMTP)"]:::module
            SmsSvc["SMS Service"]:::module
        end
    end

    %% External Dependencies
    subgraph "External Systems"
        direction TB
        Postgres["PostgreSQL Database"]:::datastore
        Redis["Redis Cache"]:::datastore
        MinIO["MinIO Object Storage"]:::datastore
        WeatherAPI["Weather API"]:::external
        CurrencyAPI["Currency API"]:::external
        PrayerAPI["Prayer Time API"]:::external
        EmailGW["SMTP Email Gateway"]:::external
        SMSGW["SMS Gateway"]:::external
    end

    %% Clients to Application
    AdminUI -->|"HTTPS/JSON"| JwtFilter
    MiniApp -->|"HTTPS/JSON"| JwtFilter
    Guide -->|"HTTPS/JSON"| JwtFilter
    I18n -->|"HTTPS/JSON"| JwtFilter
    SwaggerUI -->|"HTTPS/JSON"| OpenAPI
    TelegramPlatform -->|"Webhook JSON"| DispatcherTelegram

    %% Security to Controllers
    JwtFilter -->|passes to| SecurityCfg
    SecurityCfg -->|routes to| DispatcherSite

    %% Site Flow
    DispatcherSite -->|"calls"| SiteServices
    SiteServices -->|"uses"| SiteRepos
    SiteRepos -->|"JPA/JDBC"| Postgres
    SiteServices -->|"caches"| Redis
    SiteServices -->|"stores"| MinioSvc
    SiteServices -->|"sends email"| MailSvc
    SiteServices -->|"sends SMS"| SmsSvc

    %% Telegram Flow
    DispatcherTelegram -->|"calls"| UpdateDispatcher["Update Dispatcher"]:::module
    UpdateDispatcher -->|"calls"| TelegramServices
    TelegramServices -->|"uses"| TelegramRepos
    TelegramRepos -->|"JPA/JDBC"| Postgres
    TelegramServices -->|"calls"| WeatherAPI
    TelegramServices -->|"calls"| CurrencyAPI
    TelegramServices -->|"calls"| PrayerAPI
    TelegramServices -->|"sends message to"| TelegramPlatform

    %% Cross-cutting configs
    Liquibase -->|on startup| Postgres
    AsyncCfg -->|provides threads to| SiteServices
    CacheCfg -->|configures| Redis

    %% Infra services to external
    MinioSvc -->|"S3 API"| MinIO
    MailSvc -->|"SMTP"| EmailGW
    SmsSvc -->|"HTTP"| SMSGW

    %% Click Events
    click AdminUI "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/resources/static/admin-panel"
    click MiniApp "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/resources/static/tg-bot-mini-app"
    click Guide "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/resources/static/guide"
    click I18n "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/resources/static/i18n"
    click OpenAPI "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/config/OpenApiConfig.java"
    click JwtFilter "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/config/security/JwtAuthenticationFilter.java"
    click SecurityCfg "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/config/security/SecurityConfig.java"
    click DispatcherSite "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/site/controller"
    click DispatcherTelegram "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/telegram/controller/TelegramWebhookController.java"
    click UpdateDispatcher "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/telegram/controller/UpdateDispatcherService.java"
    click SiteServices "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/site/service"
    click TelegramServices "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/telegram/service"
    click SiteRepos "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/site/repository"
    click TelegramRepos "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/telegram/repository"
    click SiteEntities "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/site/model"
    click TelegramEntities "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/java/uz/kundalik/telegram/model"
    click Liquibase "https://github.com/abdulbositabdurahimovdeveloper/kundalik/tree/main/src/main/resources/db/changelog"
    click AsyncCfg "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/config/AsyncConfig.java"
    click CacheCfg "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/config/cache/CacheConfig.java"
    click MinioSvc "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/service/minio/MinioService.java"
    click MailSvc "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/service/mail/MailServiceImpl.java"
    click SmsSvc "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/service/sms/SmsService.java"
    click WeatherAPI "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/telegram/apiclient/WeatherApiClient.java"
    click CurrencyAPI "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/telegram/apiclient/CurrencyApiClient.java"
    click PrayerAPI "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/telegram/apiclient/PrayerTimeApiClient.java"
    click EmailGW "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/resources/application.yaml"
    click ApplicationProperties "https://github.com/abdulbositabdurahimovdeveloper/kundalik/blob/main/src/main/java/uz/kundalik/site/properties/ApplicationProperties.java"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef module fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef datastore fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef external fill:#ffccbc,stroke:#e64a19,color:#b71c1c
    classDef security fill:#ffcdd2,stroke:#e53935,color:#b71c1c
    classDef config fill:#d1c4e9,stroke:#5e35b1,color:#311b92
```
