# cenixeriadev/urlshortner architecture

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

- Interactive diagram: https://gitdiagram.com/cenixeriadev/urlshortner
- Repository: https://github.com/cenixeriadev/urlshortner

## Overview

##### Project Overview
- This project is a full-stack URL shortening service built using a Spring Boot backend and an Angular-based frontend. It is designed with a layered architecture that promotes separation of concerns and is built with horizontal scaling in mind. Although it currently runs as a single application, its structure paves the way for a transition to a more distributed or microservice-based architecture, complete with an API Gateway and load balancing.

##### And Represent Main System Components
- Frontend Component:
- Files and configurations from the “frontend” directory such as index.html, Angular modules, and routing (app.routes.ts).

- Backend Component:
▪ Controller Layer:
- ReadController and WriteController components.
- That controllers handle incoming HTTP requests and route them to proper services.
▪ Service Layer:
- Core services like UrlShortnerService, RedisService, and ZooKeeperService that implement business logic including URL shortening, caching, and unique sequence generation.
- Base62Converter utility as part of the business logic.
▪ Repository Layer:
- ShortUrlRepository, indicating its role in persisting URL mappings to PostgresSQL.

- API Gateway / Load Balancer:
- Even though the application currently works as a single backend service, include a representation of an “API Gateway / Load Balancer” component.
- That it maps HTTP methods (GET vs. POST/PUT/DELETE) to the respective read and write endpoints which could facilitate horizontal scaling.

- Database and Persistence:
- It via the Repository layer inside the backend.

- Caching Layer:
- “Redis” as a caching component, linked to the Service layer to illustrate faster retrieval for URL lookups.

- Distributed Coordination:
- Connection to the Service layer where Base62 encoding is applied.

- Environment/Infrastructure (Optional):

##### Defining Relationships and Interactions
- From “User/Client” to “Frontend” (for web interaction).
- From the “Frontend” to the “Backend” (REST API calls).
- Within the Backend:

##### Architectural Patterns and Design Principles
- Layered architecture (Separation of controllers, services, and repositories).
- That the system is designed with scalability in mind, with an architecture that can support an API gateway and load balancer for separating read and write operations.
- Optionally mention future extensibility towards a microservices architecture (e.g., separating read and write microservices).

##### Technical Technologies and Libraries
- Components with their relevant technologies:
- “Spring Boot” for the backend framework.
- “PostgresSQL” for database persistence.
- “Redis” for caching.
- “ZooKeeper (Apache Curator)” for distributed sequence generation.
- “Angular” for the frontend.
- “Maven” for build and dependency management.
- “Docker Compose” for container orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Client"]:::external

    subgraph "Frontend"
        FT1["Application (Angular)"]:::frontend
        F1["Index HTML"]:::frontend
        F2["App Routes"]:::frontend
        FT1 --> F1
        FT1 --> F2
    end

    subgraph "API Gateway / Load Balancer"
        AG["API Gateway / Load Balancer"]:::gateway
        AGC["ApiGatewayConfig"]:::gateway
        LBC["LoadBalancerConfig"]:::gateway
        AG --> AGC
        AG --> LBC
    end

    subgraph "Backend Service (Spring Boot)"
        BA["Backend Application"]:::backend

        subgraph "Controller Layer"
            RC["ReadController"]:::controller
            WC["WriteController"]:::controller
        end

        subgraph "Service Layer"
            US["UrlShortnerService"]:::service
            RS["RedisService"]:::service
            ZS["ZooKeeperService"]:::service
            BC["Base62Converter"]:::service
        end

        subgraph "Repository Layer"
            SR["ShortUrlRepository"]:::repository
        end
    end

    PS["PostgresSQL"]:::external
    RED["Redis"]:::external
    ZK["ZooKeeper (Apache Curator)"]:::external
    DC["Docker Compose"]:::external

    User -->|"web-request"| FT1
    FT1 -->|"API-call"| AG
    AG -->|"forward"| BA
    RC -->|"calls"| US
    WC -->|"calls"| US
    US -->|"persists"| SR
    US -.->|"converts"| BC
    RS -->|"caching"| RED
    ZS -->|"sequence"| ZK
    SR -->|"stores"| PS
    DC -->|"orchestrates"| BA
    DC -->|"orchestrates"| PS
    DC -->|"orchestrates"| RED
    DC -->|"orchestrates"| ZK

    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#F7D6AE,stroke:#333,stroke-width:2px;
    classDef controller fill:#E8F7AE,stroke:#333,stroke-width:2px;
    classDef service fill:#F7AEF1,stroke:#333,stroke-width:2px;
    classDef repository fill:#D6AEF7,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD8AE,stroke:#333,stroke-width:2px;
    classDef gateway fill:#C1F7C1,stroke:#333,stroke-width:2px;

    click FT1 "https://github.com/cenixeriadev/urlshortner/tree/main/frontend/"
    click F1 "https://github.com/cenixeriadev/urlshortner/blob/main/frontend/src/index.html"
    click F2 "https://github.com/cenixeriadev/urlshortner/blob/main/frontend/src/app/app.routes.ts"
    click BA "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/BackendApplication.java"
    click RC "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/controller/ReadController.java"
    click WC "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/controller/WriteController.java"
    click US "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/service/UrlShortnerService.java"
    click RS "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/service/RedisService.java"
    click ZS "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/service/ZooKeeperService.java"
    click BC "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/utils/Base62Converter.java"
    click SR "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/repository/ShortUrlRepository.java"
    click AGC "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/config/ApiGatewayConfig.java"
    click LBC "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/config/LoadBalancerConfig.java"
    click ZK "https://github.com/cenixeriadev/urlshortner/blob/main/backend/src/main/java/com/example/backend/config/ZookeeperConfig.java"
    click PS "https://github.com/cenixeriadev/urlshortner/blob/main/backend/db/data.sql"
    click DC "https://github.com/cenixeriadev/urlshortner/blob/main/docker-compose.yml"
```
