# sk-shahnawaz/go-url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/sk-shahnawaz/go-url-shortener
- Repository: https://github.com/sk-shahnawaz/go-url-shortener

## Overview

##### Main Components
- API Server: Represented by the main entry point (src/main.go) where the Echo web server listens on a configurable port (via CUSTOM_PORT_NUMBER). This is the central component that handles the incoming HTTP requests.
- Handlers Layer: The components in the src/Handlers directory that define the endpoints (/api/generate and /api/resolve). They process requests, interface with underlying logic, and return responses.
- Models & DTOs: Under src/Models, these files define the data structures used throughout the application. They represent the core data used by handlers and passed to the database.
- Database Module: Located in src/Database. This component handles:
- The connection to PostgreSQL (with configurations from the .env file).
- Database migrations (in src/Database/Migrations) using scripts generated/run via Go.
- A dedicated Dockerfile to containerize the database component.
- Documentation & Utilities: The src/docs folder contains Swagger API definitions (swagger.json and swagger.yaml) that serve documentation at /swagger/index.html. Additionally, src/Utilities supports miscellaneous functions.
- Deployment & CI/CD: Dockerfile and docker-compose.yml are used to containerize and orchestrate the application. Also, GitHub workflows, including build and labeler configs, support the continuous integration process.

##### Component Relationships and Interactions
- External Client/Browser:
- Interacts with the API server through HTTP requests. This includes:
- Health Check Endpoint – verifying that the server is running.
- API calls to /api/generate and /api/resolve.
- Accessing the Swagger UI for API documentation.
- API Server:
- Routes requests to the appropriate Handlers.
- Invokes business logic that works with the Models/DTOs.
- Delegates persistence tasks to the Database Module.
- Database Module (PostgreSQL):
- Receives queries or migration commands from the API server.
- Stores and retrieves data as per the configuration (either in-memory or using PostgreSQL).
- CI/CD Pipeline:
- GitHub Actions (configured in .github/workflows) automate build/test/deployment processes.
- Docker Compose orchestrates the entire application stack (API server and Database) during deployment/testing.

##### Architectural Patterns & Design Principles
- Modularity: Each group of files (Handlers, Models, Database, Utilities) is clearly separated to adhere to single responsibility principles.
- Environment-Driven Configuration: Use of a .env file and different settings for choosing between in-memory or PostgreSQL databases.
- Containerization: Docker and Docker Compose are used to encapsulate application components, making deployment more reproducible.
- Documentation: Built-in Swagger documentation (auto-generated via comments) helps both developers and external users understand the API.
- GitHub Actions: Continuous integration practices ensure that the application remains robust and maintainable.

##### Execution
- Configuration aspects: use of .env for environment variables, and the Docker ecosystem for running containers.
- Interactions between components and any conditional behavior (such as switching between an in-memory database vs. PostgreSQL).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["External Client/Browser"]:::client
    end

    %% API Gateway
    subgraph "API Gateway"
        APIServer["API Server (Echo Framework)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Handlers["Handlers (/api/generate, /api/resolve)"]:::logic
        Models["Models (Data Structures)"]:::logic
        DTOs["DTOs (Data Transfer Objects)"]:::logic
    end

    %% Documentation & Utilities
    subgraph "Documentation & Utilities"
        SwaggerDocs["Swagger Docs (/swagger/index.html)"]:::docs
        Utilities["Utilities"]:::docs
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        Database["Database Module (PostgreSQL)"]:::db
        DBClient["Postgres Client"]:::db
        Migrations["Database Migrations"]:::db
        DBDocker["DB Dockerfile"]:::db
        Database --> DBClient
        Database --> Migrations
        Database --> DBDocker
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DockerDeploy["Docker & Docker Compose"]:::infra
        CICD["CI/CD Pipeline (GitHub Actions)"]:::infra
    end

    %% Connections Between Layers
    Client -->|"HTTP_Request"| APIServer
    APIServer -->|"Routes"| Handlers
    Handlers -->|"Uses"| Models
    Handlers -->|"Uses"| DTOs
    APIServer -->|"Serves"| SwaggerDocs
    APIServer -->|"DB_Operations"| Database
    DockerDeploy -->|"Deploys"| APIServer
    DockerDeploy -->|"Deploys"| Database
    CICD -->|"Triggers"| DockerDeploy

    %% Click Events
    click APIServer "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/main.go"
    click Handlers "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/Handlers/handlers.go"
    click Models "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/Models/models.go"
    click DTOs "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/Models/DTOs/data.go"
    click Database "https://github.com/sk-shahnawaz/go-url-shortener/tree/master/src/Database"
    click DBClient "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/Database/postgresClient.go"
    click Migrations "https://github.com/sk-shahnawaz/go-url-shortener/tree/master/src/Database/Migrations"
    click DBDocker "https://github.com/sk-shahnawaz/go-url-shortener/tree/master/src/Database/Dockerfile"
    click SwaggerDocs "https://github.com/sk-shahnawaz/go-url-shortener/tree/master/src/docs"
    click Utilities "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/src/Utilities/library.go"
    click DockerDeploy "https://github.com/sk-shahnawaz/go-url-shortener/tree/master/Dockerfile"
    click DockerDeploy "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/docker-compose.yml"
    click CICD "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/.github/workflows/build.yml"
    click CICD "https://github.com/sk-shahnawaz/go-url-shortener/blob/master/.github/workflows/labeler.yml"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef logic fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef db fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef infra fill:#FFA500,stroke:#000,stroke-width:2px;
```
