# ssaisriharsha/url-shortener architecture

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

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

## Overview

##### Project type and purpose
- This is a backend Java Spring Boot microservice whose sole purpose is to shorten long URLs and track click analytics.
- It exposes a REST API for generating and resolving short URLs and includes a simple auth mechanism for user-specific operations.

##### File structure
- Top level: Maven wrapper files, `pom.xml`, README.
- `src/main/java/com/ssaisriharsha/UrlShortener` organizes code by layer:
- Config (security)
- Controller (AuthController, URLRestController)
- Service (AuthService, URLService, AppUserDetailsService)
- Repository (AppUserRepo, URLRepo)
- Entities (AppUser, URLEntity)
- DTOs (AppUserDTO, URLEntityDTO)
- Utilities (ShortURLGenerator, DomainProtocolExtractor)
- `src/main/resources/application.properties` holds DB connection and CORS.
- Tests are under `src/test`.

##### README for additional insights
- Uses Spring MVC, Spring Data JPA, PostgreSQL.
- Features: `GET /api/{shortURL}`, `POST /api/shorten`
- Tracks clicks, every 5th click redirects to google.com (extensible to ads).
- CORS enabled; standalone JAR deployable.

a. Main components
- Client (e.g., Web UI, Postman, mobile app)
- Spring Boot Application
- Security Layer (Spring Security config, AppUserDetails)
- API Layer (AuthController, URLRestController)
- Business Layer (AuthService, URLService)
- Data Layer (Spring Data JPA Repositories)
- Utilities (ShortURLGenerator, DomainProtocolExtractor)
- PostgreSQL Database
- External Redirect/Ad Service (e.g., google.com or ad server)

b. Relationships & interactions
1. Client → API Layer: HTTP(s) requests
2. Requests pass through Security Layer
3. Controller dispatches to Service
4. Service uses Utilities for URL processing
5. Service ↔ Repository for DB CRUD
6. Redirect flow: URLService checks click count → either direct DB URL or invokes external redirect
7. Responses flow back to client

c. Architectural patterns & design principles
- Layered Architecture (Controller → Service → Repository)
- DTO Pattern for request/response decoupling
- Separation of Concerns (Security config isolated under Config)
- Utility components for cross-cutting concerns (URL generation, protocol handling)
- Spring Data JPA abstracts persistence layer

d. Relevant technologies & frameworks
- Spring Boot (application framework)
- Spring MVC (REST controllers)
- Spring Security (auth & route protection)
- Spring Data JPA (ORM)
- PostgreSQL (relational storage)
- Java’s `SecureRandom` & `java.net.http` for short-URL generation & optional HTTP calls

##### Detail
- Layer explicitly—do not lump all server code into one block.
- Security filter chain before controllers.
- Where DTOs translate to Entities.
- Click-count logic branch to external redirect.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client (Web/Mobile/Postman)"]:::client

    subgraph "Spring Boot Application"
        subgraph "Security Layer"
            SC["SecurityConfig"]:::security
            UD["AppUserDetails"]:::security
        end

        subgraph "API Layer"
            AC["AuthController"]:::controller
            RC["URLRestController"]:::controller
        end

        subgraph "Business Layer"
            AuthS["AuthService"]:::service
            URLS["URLService"]:::service
            UDServ["AppUserDetailsService"]:::service
        end

        subgraph "Data Layer"
            AU["AppUserRepo"]:::repo
            UR["URLRepo"]:::repo
        end

        subgraph "Entities & DTOs"
            EntityU["AppUser"]:::entity
            EntityURL["URLEntity"]:::entity
            DTOU["AppUserDTO"]:::dto
            DTOURL["URLEntityDTO"]:::dto
        end

        subgraph "Utilities" 
            SU["ShortURLGenerator"]:::util
            DPE["DomainProtocolExtractor"]:::util
        end

        Props["application.properties"]:::config
        Main["UrlShortenerApplication"]:::main
    end

    DB["PostgreSQL Database"]:::db
    Ext["External Redirect/Ad Service"]:::external

    %% Flows
    Client -->|"HTTP(S) Request"| SC
    SC --> AC
    SC --> RC
    AC -->|"authenticate"| AuthS
    AC -->|"returns JWT/Response"| Client
    RC -->|"shorten/resolve"| URLS
    URLS -->|"returns URL/redirect"| RC
    RC -->|"response"| Client

    AuthS --> AU
    URLS --> UR
    AU -->|JDBC| DB
    UR -->|JDBC| DB
    URLS --> SU
    URLS --> DPE

    URLS -->|click count logic| Decision{"5th Click?"}
    Decision -->|No| Client
    Decision -->|Yes| Ext

    %% Configuration and Boot
    Main --> SC
    Main --> AC
    Main --> RC

    %% Click Events
    click SC "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Config/Security/SecurityConfig.java"
    click UD "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Config/Security/AppUserDetails.java"
    click AC "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Controller/AuthController.java"
    click RC "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Controller/URLRestController.java"
    click AuthS "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Service/AuthService.java"
    click URLS "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Service/URLService.java"
    click UDServ "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Service/AppUserDetailsService.java"
    click AU "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Repository/AppUserRepo.java"
    click UR "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Repository/URLRepo.java"
    click EntityU "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Entities/AppUser.java"
    click EntityURL "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Entities/URLEntity.java"
    click DTOU "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/DTOs/AppUserDTO.java"
    click DTOURL "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/DTOs/URLEntityDTO.java"
    click SU "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Utilities/ShortURLGenerator.java"
    click DPE "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/Utilities/DomainProtocolExtractor.java"
    click Props "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/resources/application.properties"
    click Main "https://github.com/ssaisriharsha/url-shortener/blob/main/src/main/java/com/ssaisriharsha/UrlShortener/UrlShortenerApplication.java"

    %% Styles
    classDef client fill:#eef,stroke:#66c,stroke-width:2px
    classDef security fill:#f4e1f7,stroke:#c27bcc,stroke-width:2px
    classDef controller fill:#cde8ff,stroke:#0a6ebd,stroke-width:2px
    classDef service fill:#d0f0c0,stroke:#3d8b37,stroke-width:2px
    classDef repo fill:#ffebcc,stroke:#d97706,stroke-width:2px
    classDef entity fill:#f0f0f0,stroke:#666,stroke-width:1px,stroke-dasharray:5 5
    classDef dto fill:#f0f0f0,stroke:#666,stroke-width:1px,stroke-dasharray:5 5
    classDef util fill:none,stroke:#e67e22,stroke-width:2px,stroke-dasharray:5 5
    classDef db fill:#d5f5e3,stroke:#239b56,stroke-width:2px,shape:cylinder
    classDef external fill:#fdebd0,stroke:#d35400,stroke-width:2px
    classDef config fill:#f9e79f,stroke:#b7950b,stroke-width:2px
    classDef main fill:#e8daef,stroke:#8e44ad,stroke-width:2px
```
