# aleksk1ng/go-clean-architecture-rest-api architecture

> Architecture diagram of the GitHub repository aleksk1ng/go-clean-architecture-rest-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aleksk1ng/go-clean-architecture-rest-api
- Repository: https://github.com/aleksk1ng/go-clean-architecture-rest-api

## Overview

##### Project type and purpose
- This is a backend‐only REST API microservice written in Go, following Uncle Bob’s Clean Architecture.
- It exposes HTTP endpoints (via Echo) for domains such as auth, news, comments, and session, persisting data in PostgreSQL and Redis, storing files in S3 (MinIO), and instrumenting with Prometheus, Grafana, and Jaeger.

##### File structure
- cmd/api: entrypoint (main.go) that wires together router, middleware, handlers, use cases, repositories, and config.
- config: Viper‐based configuration for local, Docker, and production.
- internal: core business logic, split by domain:
- delivery/http (handlers & routes)
- usecase (application business rules)
- repository (database/Redis/AWS implementations)
- mock (test doubles)
- internal/middleware & internal/server: HTTP middleware chain (auth, CSRF, logging, metrics, sanitizer) and server bootstrap.
- pkg: shared utilities and infrastructure helpers (DB connection, JWT, sanitization, logger, metrics, HTTP errors).
- migrations: SQL scripts to initialize and evolve the schema.
- docker & docker-compose: container images and multi‐container setups for dev, debug, monitoring.
- docs: Swagger definitions.
- ssl: certificates for local HTTPS.

##### README insights
- Technology stack: Echo, sqlx/pgx, go-redis, zap, validator, jwt-go, migrate, MinIO, Bluemonday, Swag, testing frameworks, Docker.
- Development workflows: make local/run, compose files, UIs for Swagger, Jaeger, Prometheus, Grafana.

##### Main components & their interactions
a. API Gateway & HTTP Server
- Echo HTTP server (cmd/api → internal/server)
- Global middleware chain (auth, CSRF, metrics, logging, sanitize)
b. Delivery Layer
- Domain‐specific handlers and routes (internal/*/delivery/http)
c. Application Layer (Use Cases)
- Business rules orchestrated by usecase interfaces (internal/*/usecase)
d. Infrastructure Layer (Repositories & Clients)
- PostgreSQL repositories (sqlx/pgx)
- Redis repositories (go-redis)
- AWS S3/MinIO client (minio-go)
e. Shared Services & Utilities
- Configuration loader (Viper)
- Logger (Zap)
- JWT utilities, validators, sanitizers, metrics emitters
f. External Systems
- PostgreSQL, Redis, MinIO/S3
- Prometheus (metrics), Grafana (dashboards), Jaeger (tracing)
g. Dev & CI/CD
- Dockerfiles, docker‐compose (dev/delve), GitHub Actions (test.yml)

##### Architectural patterns & principles
- Clean Architecture (onion or hexagonal layers) with dependency inversion:
- Outward layers implement interfaces defined inward.
- Separation of concerns: delivery → usecase → repository.
- Single responsibility per package/domain.
- Testability through dependency injection and mocks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and components

    subgraph "API Layer"
        direction TB
        Client["Client"]:::external
        Echo["Echo HTTP Server"]:::api
        Middleware["Global Middleware\n(auth, CSRF, metrics,\nlogging, sanitize)"]:::api
        Client -->|HTTP Request| Echo
        Echo -->|handle| Middleware
    end

    subgraph "Delivery Layer"
        direction TB
        AuthHandler["Auth Handler\n(routes & handlers)"]:::delivery
        NewsHandler["News Handler\n(routes & handlers)"]:::delivery
        CommentsHandler["Comments Handler\n(routes & handlers)"]:::delivery
        SessionHandler["Session Handler"]:::delivery
        Middleware --> AuthHandler
        Middleware --> NewsHandler
        Middleware --> CommentsHandler
        Middleware --> SessionHandler
    end

    subgraph "Use Case Layer"
        direction TB
        AuthUseCase["Auth UseCase"]:::usecase
        NewsUseCase["News UseCase"]:::usecase
        CommentsUseCase["Comments UseCase"]:::usecase
        SessionUseCase["Session UseCase"]:::usecase
        AuthHandler -->|invoke| AuthUseCase
        NewsHandler -->|invoke| NewsUseCase
        CommentsHandler -->|invoke| CommentsUseCase
        SessionHandler -->|invoke| SessionUseCase
    end

    subgraph "Infrastructure Layer"
        direction TB
        subgraph Repositories
            direction TB
            AuthPG["Auth PG Repository"]:::infra
            AuthRedisRepo["Auth Redis Repository"]:::infra
            AuthAWSRepo["Auth AWS Repository"]:::infra
            NewsPG["News PG Repository"]:::infra
            NewsRedisRepo["News Redis Repository"]:::infra
            CommentsPG["Comments PG Repository"]:::infra
            SessionRedis["Session Redis Repository"]:::infra
        end
        subgraph Clients
            direction TB
            Postgres["PostgreSQL"]:::external
            Redis["Redis"]:::external
            MinIO["S3/MinIO"]:::external
        end
        AuthUseCase --> AuthPG
        AuthUseCase --> AuthRedisRepo
        AuthUseCase --> AuthAWSRepo
        NewsUseCase --> NewsPG
        NewsUseCase --> NewsRedisRepo
        CommentsUseCase --> CommentsPG
        SessionUseCase --> SessionRedis
        AuthPG --> Postgres
        NewsPG --> Postgres
        CommentsPG --> Postgres
        AuthRedisRepo --> Redis
        NewsRedisRepo --> Redis
        SessionRedis --> Redis
        AuthAWSRepo --> MinIO
    end

    subgraph "Shared Utilities & Services"
        direction TB
        Config["Config Loader (Viper)"]:::util
        Logger["Zap Logger"]:::util
        JWT["JWT Utilities"]:::util
        CSRFUtil["CSRF Utility"]:::util
        Sanitize["Sanitizer Utility"]:::util
        Metrics["Metrics Utility"]:::util
        HttpErr["HTTP Error Handler"]:::util
        UseCaseServices["UseCase ↔ Logger/Tracer/Metrics"]:::util
        Config --> Echo
        Logger --> Echo
        Logger --> AuthUseCase
        Logger --> NewsUseCase
        Logger --> CommentsUseCase
        Logger --> SessionUseCase
        JWT --> AuthHandler
        CSRFUtil --> Middleware
        Sanitize --> Middleware
        Metrics --> Middleware
        UseCaseServices --> UseCaseServices
    end

    subgraph "Observability & CI/CD"
        direction TB
        Prom["Prometheus"]:::external
        Graf["Grafana"]:::external
        Jaeger["Jaeger"]:::external
        DockerCompose["Docker Compose"]:::external
        CI["GitHub Actions"]:::external
        Prom --> Metrics
        Jaeger --> Logger
        Graf --> Prom
        CI -->|build/test| Echo
    end

    %% Connections
    Echo -->|routes| AuthHandler
    Echo -->|routes| NewsHandler

    %% Click Events
    click Echo "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/cmd/api/main.go"
    click Middleware "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/middleware/middlewares.go"
    click AuthHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/delivery/http/handlers.go"
    click AuthHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/delivery/http/routes.go"
    click NewsHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/news/delivery/http/handlers.go"
    click NewsHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/news/delivery/http/routes.go"
    click CommentsHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/comments/delivery/http/hanldlers.go"
    click CommentsHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/comments/delivery/http/routes.go"
    click SessionHandler "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/session/redis_repository.go"
    click AuthUseCase "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/usecase/usecase.go"
    click NewsUseCase "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/news/usecase/usecase.go"
    click CommentsUseCase "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/comments/usecase/usecase.go"
    click SessionUseCase "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/session/usecase/usecase.go"
    click AuthPG "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/repository/pg_repository.go"
    click AuthRedisRepo "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/repository/redis_repository.go"
    click AuthAWSRepo "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/auth/repository/aws_repository.go"
    click NewsPG "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/news/repository/pg_repository.go"
    click NewsRedisRepo "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/news/repository/redis_repository.go"
    click CommentsPG "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/comments/repository/pg_repository.go"
    click SessionRedis "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/internal/session/repository/redis_repository.go"
    click Config "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/config/config.go"
    click Postgres "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/db/postgres/db_conn.go"
    click Redis "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/db/redis/conn.go"
    click MinIO "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/db/aws/aws.go"
    click Logger "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/logger/zap_logger.go"
    click JWT "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/utils/jwt.go"
    click CSRFUtil "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/csrf/csrf.go"
    click Sanitize "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/sanitize/sanitize.go"
    click Metrics "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/metric/metric.go"
    click HttpErr "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/pkg/httpErrors/http_errors.go"
    click CI "https://github.com/aleksk1ng/go-clean-architecture-rest-api/blob/master/.github/workflows/test.yml"

    %% Styles
    classDef api fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef delivery fill:#f1f8e9,stroke:#33691e,color:#33691e;
    classDef usecase fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20;
    classDef infra fill:#fff3e0,stroke:#e65100,color:#e65100;
    classDef external fill:#eceff1,stroke:#455a64,color:#455a64;
    classDef util fill:#fce4ec,stroke:#880e4f,color:#880e4f;
```
