# imokkkk/short-link-generator architecture

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

- Interactive diagram: https://gitdiagram.com/imokkkk/short-link-generator
- Repository: https://github.com/imokkkk/short-link-generator

## Overview

##### Main Components
- Client Interface / Web Layer:
- Represented by the "short-link-web" module.
- Contains the Application entry point, controllers (e.g., UrlController), static resources (HTML, CSS, JS), and REST endpoints to facilitate URL conversion.
- Core Service Layer:
- Found in the "short-link-core" module.
- Includes application configuration, aspect modules for rate limiting (RateLimiterAspect), background jobs (e.g., ShortURLReceiverJob, shortURLSendJob) and other business logic (e.g., UrlService and its implementation).
- Contains integration components with Redis, Kafka, and scheduling tasks for URL preloading.
- Data Access Layer:
- Located in the "short-link-dal" module.
- Responsible for interacting with the database (e.g., UrlMapper, SQL mappings in UrlMapper.xml, and the init.sql script).
- Common Utilities/Shared Library:
- The "short-link-common" module carries shared utilities and constants (e.g., CommonConstant, ShortUrlUtil), exception handling, response models, and helper classes (such as the BloomFilterUtil).

- Incoming HTTP requests are routed to the web layer (short-link-web) where a controller (UrlController) accepts a long URL conversion request.
- The web layer calls into the core service layer (UrlService/UrlServiceImpl) for business logic to generate or retrieve a short URL.
- The core layer uses the data access layer (short-link-dal) to persist or retrieve URL records from the database.
- The pre-generated URL pool mechanism (via LinkedBlockingQueue) is managed by a dedicated background thread that monitors queue size. When the URL pool drops below a threshold (e.g., 200 URLs), it triggers the reload from the database.
- Asynchronous operations using Kafka are used for multi-threaded, decoupled persistence when pre-generated URLs are saved.
- Redis is integrated to apply a Bloom filter for efficient and near-real-time duplicate checks.
- Additional configuration and resilience (via SpringCloud Config and Resilience4j) ensure dynamic updates and concurrency control.

##### Architectural Patterns and Design Principles
- Layered architecture to enforce separation of concerns: presentation (web), business logic (core), and persistence (dal).
- Modular design (using Maven multi-module structure) to separate concerns and encourage maintainability.
- Asynchronous data processing via message queues (Kafka) to decouple processes.
- Use of caching and filtering (Redis and Bloom filters) to improve performance and reduce collisions.
- Background task scheduling and monitoring for the URL pool (using a dedicated thread and queue mechanism).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client("Browser/Client"):::external

    %% Web Module
    subgraph "Web Module"
        A("Application Entry Point"):::web
        UC("UrlController"):::web
        Static("Static Resources"):::web
    end

    %% Core Module
    subgraph "Core Module"
        US("UrlService (Interface)"):::core
        USImpl("UrlServiceImpl"):::core
        RLA("RateLimiterAspect"):::core
        SRJ("ShortURLReceiverJob"):::core
        SSJ("shortURLSendJob"):::core
        Config("Configuration"):::core
    end

    %% Data Access Module
    subgraph "Data Access Module"
        UR("UrlRequest"):::dal
        UM("UrlMapper XML"):::dal
        U("Url (Entity)"):::dal
    end

    %% Common Module
    subgraph "Common Module"
        CC("Common Constants"):::common
        BF("BloomFilterUtil"):::common
        SU("ShortUrlUtil"):::common
        EH("Exception Handling"):::common
    end

    %% Infrastructure / External Systems
    subgraph "Infrastructure"
        DB("Database"):::infra
        Redis("Redis"):::infra
        Kafka("Kafka"):::infra
        DCI("Docker/CD Integration"):::infra
    end

    %% Connections
    Client -->|"HTTP_Request"| A
    A -->|"Routes_Request"| UC
    UC -->|"Invokes_Service"| US
    US -->|"Delegate_to_Impl"| USImpl
    USImpl -->|"DB_Operation"| UM
    UM -->|"Executes_SQL"| U
    U ---|"Persists_Data"| DB

    %% Core Background and Configurations
    USImpl -->|"Triggers"| SRJ
    USImpl -->|"Triggers"| SSJ
    RLA ---|"Enforces_RateLimit"| UC

    Config ---|"Configures_BloomFilter"| BF
    Config ---|"Configures_Messaging"| Kafka
    Config ---|"Configures_Caching"| Redis

    SRJ -->|"Updates_PreGenPool"| USImpl
    SSJ -->|"Sends_Messages"| Kafka

    %% Common Utilities integration
    CC --- USImpl
    SU --- USImpl
    EH --- USImpl

    %% External Infrastructure Calls
    USImpl ---|"Cache_Check"| Redis

    %% Styles
    classDef web fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef core fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef dal fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef common fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFDEAD,stroke:#000,stroke-width:2px;

    %% Click Events for Web Module
    click A "https://github.com/imokkkk/short-link-generator/blob/master/short-link-web/src/main/java/cn/imokkkk/Application.java"
    click UC "https://github.com/imokkkk/short-link-generator/blob/master/short-link-web/src/main/java/cn/imokkkk/controller/UrlController.java"
    click Static "https://github.com/imokkkk/short-link-generator/tree/master/short-link-web/src/main/resources/static"

    %% Click Events for Core Module
    click US "https://github.com/imokkkk/short-link-generator/blob/master/short-link-core/src/main/java/cn/imokkkk/service/UrlService.java"
    click USImpl "https://github.com/imokkkk/short-link-generator/blob/master/short-link-core/src/main/java/cn/imokkkk/service/UrlServiceImpl.java"
    click SRJ "https://github.com/imokkkk/short-link-generator/blob/master/short-link-core/src/main/java/cn/imokkkk/job/ShortURLReceiverJob.java"
    click SSJ "https://github.com/imokkkk/short-link-generator/blob/master/short-link-core/src/main/java/cn/imokkkk/job/shortURLSendJob.java"
    click RLA "https://github.com/imokkkk/short-link-generator/blob/master/short-link-core/src/main/java/cn/imokkkk/aspect/RateLimiterAspect.java"
    click Config "https://github.com/imokkkk/short-link-generator/tree/master/short-link-core/src/main/java/cn/imokkkk/config"

    %% Click Events for Data Access Module
    click U "https://github.com/imokkkk/short-link-generator/blob/master/short-link-dal/src/main/java/cn/imokkkk/pojo/Url.java"
    click UR "https://github.com/imokkkk/short-link-generator/blob/master/short-link-dal/src/main/java/cn/imokkkk/request/UrlRequest.java"
    click UM "https://github.com/imokkkk/short-link-generator/blob/master/short-link-dal/src/main/resources/cn/imokkkk/mapper/UrlMapper.xml"

    %% Click Events for Common Module
    click CC "https://github.com/imokkkk/short-link-generator/tree/master/short-link-common/src/main/java/cn/imokkkk/constant"
    click BF "https://github.com/imokkkk/short-link-generator/blob/master/short-link-common/src/main/java/cn/imokkkk/util/BloomFilterUtil.java"
    click SU "https://github.com/imokkkk/short-link-generator/blob/master/short-link-common/src/main/java/cn/imokkkk/util/ShortUrlUtil.java"
    click EH "https://github.com/imokkkk/short-link-generator/tree/master/short-link-common/src/main/java/cn/imokkkk/exception"
```
