# hieplp/url-shorten architecture

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

- Interactive diagram: https://gitdiagram.com/hieplp/url-shorten
- Repository: https://github.com/hieplp/url-shorten

## Overview

##### Project type and purpose
- This is a full-stack, microservice-based URL Shortener application.
- Front-end: a Vue 3 SPA (web-services).
- Back-end: a set of Java/Vert.x microservices—API Gateway, Auth, User, Shortener, Statistic—plus a Common library.
- Supporting infrastructure: MariaDB, Kafka, Elasticsearch, Logstash, and Docker Compose orchestration.

##### File structure
- Top-level microservice folders:
- auth-services
- user-services
- shorten-services
- statistic-services
- gateway-services
- common-services (shared library)
- Front-end: web-services.
- Docker: docker-compose.yml and service-specific Dockerfiles; extensions for ELK stack.
- Each service uses the same pattern: Application entry, config modules, controllers, handlers, repositories, services, Kafka consumers/producers (where applicable).
- common-services contains shared annotations, config classes, models, payloads, repository bases, utilities.
- SQL schemas under docker/sql.
- CI/build scripts: build.sh, gradlew, Dockerfiles.

##### Insights from README
- Microservices communicate via REST through the Gateway; Kafka for click events; Logstash forwards statistics from MariaDB to Elasticsearch; UI uses Axios to call the Gateway.
- Databases: three MariaDB schemas (shortenUser, shortenUrl, shortenStatistic).
- Elasticsearch + Kibana for analytics and monitoring.

##### Elements
- Clear, consistent labels for each service, database, and external component.
- UI layer (e.g., blue rectangle)
- API layer (Gateway – green)
- Microservices (e.g., orange)
- Shared library (e.g., gray note)
- Annotations for protocols (HTTP/JSON, JDBC/jOOQ, Kafka topics, SQL, Elasticsearch queries).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UI["Web UI (Vue SPA)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Gateway["API Gateway"]:::api
    end

    %% Business Services
    subgraph "Business Services"
        direction TB
        AuthSvc["Auth Service\n(JWT Issuance)"]:::service
        UserSvc["User Service\n(User Profile)"]:::service
        ShortenSvc["Shortener Service\n(Create/Redirect URLs)"]:::service
        StatSvc["Statistic Service\n(Click Events Consumer)"]:::service
    end

    %% Shared Library
    CommonLib["Common Library\n(Shared Code)"]:::common

    %% Infrastructure under Docker Compose
    subgraph "Docker Compose"
        direction TB
        MariaDB["MariaDB\n(shortenUser, shortenUrl, shortenStatistic)"]:::db
        Kafka["Kafka Cluster\n(url.clicked topic)"]:::broker
        Logstash["Logstash"]:::infra
        Elasticsearch["Elasticsearch\n+ Kibana"]:::infra
    end

    %% Connections
    UI -->|"HTTP/JSON (Axios, JWT)"| Gateway
    Gateway -->|"REST Auth"| AuthSvc
    Gateway -->|"REST User"| UserSvc
    Gateway -->|"REST Shorten"| ShortenSvc
    ShortenSvc -->|"Kafka url.clicked"| Kafka
    Kafka -->|"Consume Events"| StatSvc
    StatSvc -->|"JDBC/jOOQ"| MariaDB
    Logstash -->|"SQL → Elasticsearch"| Elasticsearch
    StatSvc -->|"Elasticsearch Query"| Elasticsearch

    %% Click Events
    click UI "https://github.com/hieplp/url-shorten/tree/dev/web-services/"
    click Gateway "https://github.com/hieplp/url-shorten/blob/dev/gateway-services/src/main/java/com/hieplp/url/gateway/Application.java"
    click AuthSvc "https://github.com/hieplp/url-shorten/blob/dev/auth-services/src/main/java/com/hieplp/url/auth/Application.java"
    click UserSvc "https://github.com/hieplp/url-shorten/blob/dev/user-services/src/main/java/com/hieplp/url/user/Application.java"
    click ShortenSvc "https://github.com/hieplp/url-shorten/blob/dev/shorten-services/src/main/java/com/hieplp/url/shorten/Application.java"
    click StatSvc "https://github.com/hieplp/url-shorten/blob/dev/statistic-services/src/main/java/com/hieplp/url/statistic/Application.java"
    click CommonLib "https://github.com/hieplp/url-shorten/tree/dev/common-services/"
    click MariaDB "https://github.com/hieplp/url-shorten/tree/dev/docker/sql/"
    click Logstash "https://github.com/hieplp/url-shorten/tree/dev/docker/logstash/Dockerfile"
    click Elasticsearch "https://github.com/hieplp/url-shorten/tree/dev/docker/elasticsearch/Dockerfile"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0066CC,color:#003366;
    classDef api fill:#D6F5D6,stroke:#33A02C,color:#1B5E20;
    classDef service fill:#FFE3B3,stroke:#FF8C00,color:#663C00;
    classDef common fill:#E0E0E0,stroke:#999999,color:#666666,stroke-dasharray: 5 5;
    classDef db fill:#FFF2CC,stroke:#B8860B,color:#8B4513;
    classDef broker fill:#E8EAF6,stroke:#3F51B5,color:#1A237E;
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,color:#424242;
```
