URL-SHORTENER-DIAGRAMS.md

URL Shortener Diagrams

This markdown file contains various diagrams illustrating the system design, flows, and architecture of the URL Shortener microservice. All diagrams are rendered using Mermaid syntax for easy visualization in compatible viewers (e.g., GitHub, Markdown editors with Mermaid support).

1. High-Level Architecture Diagram

This flowchart shows the overall system components and their interactions.

graph TD
    A[Client/User] -->|"POST /api/shorten"| B[API Gateway/Controller]
    A -->|"GET /{shortCode}"| B
    A -->|"GET /api/analytics/{shortCode}"| B
    B --> C[UrlService]
    C --> D[UrlRepository]
    D --> E[PostgreSQL Database]
    B -->|"302 Redirect"| A
    subgraph SpringBootApp[Spring Boot Application]
        B[UrlController]
        C[UrlService]
        D[UrlRepository]
    end
    F[Docker Container] -->|"Hosts"| H[Spring Boot App]
    G[Heroku/Cloud Platform] -->|"Deploys"| F
    H --> B
    H --> C
    H --> D

Loading

2. Database Schema Diagram

This ER diagram represents the database structure for the URLs table.

erDiagram
    URLS {
        bigint id PK "Auto-increment"
        varchar original_url "NOT NULL"
        varchar short_code "UNIQUE NOT NULL"
        int click_count "DEFAULT 0"
        timestamp created_at "DEFAULT CURRENT_TIMESTAMP"
    }

Loading

3. Sequence Diagram: URL Shortening

This sequence diagram illustrates the flow for shortening a URL.

sequenceDiagram
    participant Client
    participant Controller as UrlController
    participant Service as UrlService
    participant Repo as UrlRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /api/shorten {originalUrl}
    Controller->>Service: shortenUrl(originalUrl)
    Service->>Repo: save(new Url(originalUrl, generateShortCode()))
    Repo->>DB: INSERT INTO urls
    DB-->>Repo: ID
    Repo-->>Service: Saved Url
    Service-->>Controller: shortUrl (e.g., http://host/abc123)
    Controller-->>Client: 201 Created {shortUrl}

Loading

4. Sequence Diagram: URL Redirection

This sequence diagram shows the redirection process.

sequenceDiagram
    participant Client
    participant Controller as UrlController
    participant Service as UrlService
    participant Repo as UrlRepository
    participant DB as PostgreSQL

    Client->>Controller: GET /{shortCode}
    Controller->>Service: findAndRedirect(shortCode)
    Service->>Repo: findByShortCode(shortCode)
    Repo->>DB: SELECT * FROM urls WHERE short_code = ?
    DB-->>Repo: Url (if found)
    Repo-->>Service: Url
    Service->>Repo: update click_count += 1
    Repo->>DB: UPDATE urls SET click_count = ?
    DB-->>Repo: OK
    Repo-->>Service: Updated
    Service-->>Controller: originalUrl
    Controller-->>Client: 302 Redirect to originalUrl
    Note over Client: Browser follows redirect

Loading

5. Sequence Diagram: Analytics Viewing

This sequence diagram depicts fetching analytics for a short URL.

sequenceDiagram
    participant Client
    participant Controller as UrlController
    participant Service as UrlService
    participant Repo as UrlRepository
    participant DB as PostgreSQL

    Client->>Controller: GET /api/analytics/{shortCode}
    Note over Client,Controller: Optional: Basic Auth
    Controller->>Service: getAnalytics(shortCode)
    Service->>Repo: findByShortCode(shortCode)
    Repo->>DB: SELECT * FROM urls WHERE short_code = ?
    DB-->>Repo: Url
    Repo-->>Service: Url
    Service-->>Controller: Analytics DTO {originalUrl, clickCount, createdAt}
    Controller-->>Client: 200 OK {analytics}

Loading

6. Deployment Diagram

This node diagram outlines the deployment setup, including containerization and cloud hosting.

flowchart LR
    A[Developer Machine] -->|Build & Push| B[GitHub Repo]
    B -->|CI/CD Workflow| C[Heroku App]
    C -->|Runs| D[Docker Container: Spring Boot App]
    D -->|Connects| E[Heroku Postgres Add-on]
    subgraph Production Environment
        C
        D
        E
    end
    F[Client Browser] -->|API Calls| C
    G[Monitoring: Heroku Dashboard] -->|Logs/Metrics| C

Loading

These diagrams provide a comprehensive visual overview of the URL Shortener's design. For more details, refer to the PRD and task list documents.