# azimsh3r/kaspi-price-monitor architecture

> Architecture diagram of the GitHub repository azimsh3r/kaspi-price-monitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azimsh3r/kaspi-price-monitor
- Repository: https://github.com/azimsh3r/kaspi-price-monitor

## Overview

##### Project type and purpose
- This is a backend-only, production-grade Spring Boot microservice (monolithic codebase) called “Kaspi Price Monitor & Auto-Updater.”
- Its purpose is to fetch product data from the Kaspi marketplace, apply dynamic pricing strategies (undercutting or raising prices via smart algorithms and proxy rotation), push updated prices back to Kaspi, and expose order statistics and management endpoints via a JWT-secured REST API.

##### File structure
- Top-level build files: Gradle scripts (`build.gradle.kts`, `settings.gradle.kts`, `gradlew`).
- `src/main/java/com/metaorta/kaspi` split by concern:
- `config` holds Spring Security and Redis configuration.
- `controller` defines REST controllers (Auth, Product, Order, Merchant, Session).
- `dto`, `model`, `enums` for data transfer, domain entities, and enums.
- `repository` for JPA interfaces (PostgreSQL).
- `service` for business logic, subdivided by domain:
– `order` (sync, stats, scheduling, remote client),
– `product` (fetch, sync, price-monitor),
– `security`, `proxy`, `user`, `merchant`.
- `util` for mapping and factories.
- `src/main/resources/application.properties` configures DB, Redis, JWT, and Kaspi API token.
- Presence of `OrderSyncScheduler` and use of `ScheduledExecutorService` + semaphores indicate internal scheduling and concurrency controls.

##### README for additional insights
- Architecture sketch showing client → controllers → services → proxy/calculation layers.
- Highlights external systems: Redis, PostgreSQL, Kaspi remote API.
- Security: JWT + role-based access.
- Core modules: PriceUpdateSvc (scheduler + semaphores), ProductFetchSvc, OrderStatisticsSvc, ProxyService, PriceCalcService.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        Client["External Client"]:::external
        KaspiAPI["Kaspi Marketplace REST API"]:::external
        ProxyPool["Third-Party Proxy Pool"]:::external
    end

    %% Internal Service
    subgraph "Internal Service"
        direction TB
        App["KaspiApplication"]:::infra
        SecurityConfig["SecurityConfig (JWT Filter)"]:::infra
        RedisConfig["RedisConfig"]:::infra

        subgraph "Controllers"
            direction TB
            AuthController["AuthController"]:::service
            ProductController["ProductController"]:::service
            OrderController["OrderController"]:::service
            MerchantController["MerchantController"]:::service
            UserSessionController["UserSessionController"]:::service
        end

        subgraph "Services"
            direction TB
            UserService["UserService"]:::service
            UserSessionService["UserSessionService"]:::service
            MerchantService["MerchantService"]:::service
            ProxyService["ProxyService"]:::service
            ProductFetchService["ProductFetchService"]:::service
            ProductSynchronizationService["ProductSynchronizationService"]:::service
            CompetitorService["CompetitorService"]:::service
            PriceCalculationService["PriceCalculationService"]:::service
            PriceUpdateService["PriceUpdateService"]:::service
            OrderService["OrderService"]:::service
            OrderStatisticsService["OrderStatisticsService"]:::service
            OrderSyncService["OrderSyncService"]:::service
            OrderSyncScheduler["OrderSyncScheduler"]:::infra
            OrderApiClient["OrderApiClient"]:::service
        end

        subgraph "Persistence"
            direction TB
            PostgreSQL["PostgreSQL"]:::db
            Redis["Redis"]:::db
            MerchantRepository["MerchantRepository"]:::db
            OrderRepository["OrderRepository"]:::db
            OrderEntryRepository["OrderEntryRepository"]:::db
            ProductRepository["ProductRepository"]:::db
            ProxyRepository["ProxyRepository"]:::db
            UserRepository["UserRepository"]:::db
        end

        subgraph "Utilities"
            direction TB
            OrderMapper["OrderMapper"]:::infra
            ProductFactory["ProductFactory"]:::infra
        end

        App --> SecurityConfig
        App --> RedisConfig
        SecurityConfig --> AuthController
        SecurityConfig --> ProductController
        SecurityConfig --> OrderController
        SecurityConfig --> MerchantController
        SecurityConfig --> UserSessionController

        AuthController --> UserService
        AuthController --> UserSessionService
        UserSessionController --> UserSessionService
        MerchantController --> MerchantService
        ProductController --> ProductFetchService
        ProductController --> ProductSynchronizationService
        ProductSynchronizationService --> CompetitorService
        ProductSynchronizationService --> PriceCalculationService
        PriceCalculationService --> ProxyService
        PriceUpdateService --> ProxyService
        ProductSynchronizationService --> PriceUpdateService

        OrderController --> OrderService
        OrderService --> OrderStatisticsService
        OrderService --> OrderSyncService
        OrderSyncScheduler -.->|ScheduledExecutorService+Semaphore| OrderSyncService
        OrderSyncService --> OrderApiClient
        OrderApiClient --> KaspiAPI

        ProductFetchService --> KaspiAPI
        ProductFetchService --> ProxyService

        ProxyService --> ProxyPool
        ProxyService --> Redis

        UserService --> UserRepository
        MerchantService --> MerchantRepository
        OrderService --> OrderRepository
        OrderStatisticsService --> OrderEntryRepository
        ProductSynchronizationService --> ProductRepository
        OrderSyncService --> OrderRepository

        UserSessionService --> Redis

        OrderMapper --> OrderService
        ProductFactory --> ProductFetchService

        MerchantRepository -.->|JDBC| PostgreSQL
        OrderRepository -.->|JDBC| PostgreSQL
        OrderEntryRepository -.->|JDBC| PostgreSQL
        ProductRepository -.->|JDBC| PostgreSQL
        ProxyRepository -.->|JDBC| PostgreSQL
        UserRepository -.->|JDBC| PostgreSQL

        RedisConfig --> Redis
        PostgreSQL --> RedisConfig

    end

    Client -->|"HTTP/JSON + JWT"| SecurityConfig
    Client -->|"Direct Scheduler Trigger"| OrderSyncScheduler

    %% Click Events
    click App "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/KaspiApplication.java"
    click SecurityConfig "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/config/SecurityConfig.java"
    click RedisConfig "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/config/RedisConfig.java"
    click AuthController "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/controller/AuthController.java"
    click ProductController "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/controller/ProductController.java"
    click OrderController "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/controller/OrderController.java"
    click MerchantController "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/controller/MerchantController.java"
    click UserSessionController "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/controller/UserSessionController.java"
    click UserService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/UserService.java"
    click UserSessionService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/UserSessionService.java"
    click MerchantService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/MerchantService.java"
    click ProxyService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/ProxyService.java"
    click ProductFetchService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/product/ProductFetchService.java"
    click ProductSynchronizationService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/product/ProductSynchronizationService.java"
    click CompetitorService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/product/pricemonitor/CompetitorService.java"
    click PriceCalculationService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/product/pricemonitor/PriceCalculationService.java"
    click PriceUpdateService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/product/pricemonitor/PriceUpdateService.java"
    click OrderService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/order/OrderService.java"
    click OrderStatisticsService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/order/OrderStatisticsService.java"
    click OrderSyncService "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/order/OrderSyncService.java"
    click OrderSyncScheduler "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/order/scheduler/OrderSyncScheduler.java"
    click OrderApiClient "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/service/order/client/OrderApiClient.java"

    click MerchantRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/MerchantRepository.java"
    click OrderRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/OrderRepository.java"
    click OrderEntryRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/OrderEntryRepository.java"
    click ProductRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/ProductRepository.java"
    click ProxyRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/ProxyRepository.java"
    click UserRepository "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/repository/UserRepository.java"
    click OrderMapper "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/util/OrderMapper.java"
    click ProductFactory "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/java/com/metaorta/kaspi/util/ProductFactory.java"
    click ApplicationProperties "https://github.com/azimsh3r/kaspi-price-monitor/blob/master/src/main/resources/application.properties"

    %% Styles
    classDef external fill:#D0E8FF,stroke:#0074D9,stroke-width:2px
    classDef service fill:#E0F8E0,stroke:#2D572C,stroke-width:2px
    classDef db fill:#FFE0B2,stroke:#A65600,stroke-width:2px
    classDef infra fill:#F0F0F0,stroke:#666666,stroke-width:2px
```
