# zzoe2346/url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/zzoe2346/url-shortener
- Repository: https://github.com/zzoe2346/url-shortener

## Overview

##### Project Overview & Components
- There are four main services:
a. API Gateway: Acts as the entry point for clients and routes incoming requests to the appropriate services.
b. URL Shorten Service: Generates a unique short URL (inspired by the Twitter Snowflake algorithm) for a given original URL, and then calls the Persistence service to save the mapping.
c. URL Persistence Service: Manages communication with a relational database (RDBMS) by exposing interfaces and repository methods. It stores the URL mapping data.
d. URL Redirect Service: Handles redirect requests by reading the short URL mapping and issuing a 302 redirect to the original URL.
- Each service is implemented as a separate Gradle-based Java application with clearly identified packages for controllers, domain objects, DTOs, services, and configuration. This structure implies an MVC-like design internally for each microservice.

##### Relationships & Interactions
- The API Gateway receives client requests. Based on the endpoint:
- For URL shortening operations:
→ The request is routed to the URL Shorten Service.
→ The URL Shorten Service generates the short URL and then sends a request to the URL Persistence Service to save the mapping.
→ Once confirmed, the short URL is returned to the client.
- For redirect operations:
→ The request is routed to the URL Redirect Service, which looks up the original URL from the Persistence service’s data (or possibly directly if it keeps a local cache) and returns a 302 redirect.
- The services communicate with each other via REST calls (or possibly via HTTP clients configured in Spring Boot). The URL Shorten Service acts as a client to the URL Persistence Service using a dedicated client component.

##### Architectural Patterns & Principles
- Microservices architecture: Each service is independently deployable and scalable.
- API Gateway pattern: Centralized entry point that abstracts and routes requests to underlying services.
- Separation of concerns: Each microservice is built around a single core function (shortening, persistence, redirection) which allows isolated development, testing, and deployment.
- Standard Spring Boot patterns (controllers, service layers, repository layers) and REST-based communication are evident.

##### Technologies & Frameworks
- Java, managed with Gradle.
- Spring Boot is implied by the directory structure (with src/main/java organization, configuration files, and application.properties).
- External communication libraries or Spring’s RestTemplate/WebClient likely facilitate inter-service communication (as seen in URL Shorten Service’s "client" package).

## Diagram (Mermaid)

```mermaid
graph TD
    Client("Client/Browser"):::external

    APIGateway("API Gateway\n(Spring Boot, Gradle)"):::service
    URLShorten("URL Shorten Service\n(Snowflake-ID, REST)"):::service
    URLPersistence("URL Persistence Service\n(RDBMS Interface)"):::service
    URLRedirect("URL Redirect Service\n(302 Redirect)"):::service
    Database(("RDBMS\n(Database)")):::database

    %% Client sends request to API Gateway
    Client -->|"SendsRequest"| APIGateway

    %% API Gateway routes URL shortening request
    APIGateway -->|"ShortURLRequest"| URLShorten
    URLShorten -->|"MappingRequest"| URLPersistence
    URLPersistence -->|"SaveMapping"| Database
    URLPersistence -->|"MappingConfirm"| URLShorten
    URLShorten -->|"ShortURLResponse"| APIGateway
    APIGateway -->|"ResponseWithShortURL"| Client

    %% API Gateway routes redirect request
    APIGateway -->|"RedirectLookup"| URLRedirect
    URLRedirect -->|"FetchMapping"| URLPersistence
    URLPersistence -->|"ReturnMapping"| URLRedirect
    URLRedirect -->|"302Redirect"| Client

    %% Click Events
    click APIGateway "https://github.com/zzoe2346/url-shortener/blob/main/api-gateway/src/main/java/com/urlshortener/gateway/ApiGatewayApplication.java"
    click URLShorten "https://github.com/zzoe2346/url-shortener/tree/main/url-shorten-service/src/main/java/com/urlshortener/shorten"
    click URLPersistence "https://github.com/zzoe2346/url-shortener/tree/main/url-persistence-service/src/main/java/com/urlshortener/persistence"
    click URLRedirect "https://github.com/zzoe2346/url-shortener/blob/main/url-redirect-service/src/main/java/com/urlshortener/redirect/UrlRedirectServiceApplication.java"

    %% Styles
    classDef external fill:#FFEEAD,stroke:#D4AC0D,stroke-width:2px;
    classDef service fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
```
