# 880831ian/go-auth architecture

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

- Interactive diagram: https://gitdiagram.com/880831ian/go-auth
- Repository: https://github.com/880831ian/go-auth

## Overview

##### Project type and purpose
- This is a Go-based, single-service authentication API.
- It exposes HTTP endpoints (via Gin) for login, signup, token issuance, and token revocation.
- It persists user data in MySQL (GORM) and manages tokens/blacklists in Redis.

##### File structure
- cmd/main.go: application entry point and HTTP server bootstrap
- configs/: environment configuration loader (Viper)
- routes/router.go: Gin router and endpoint registration
- middlewares/: request-level filters (JWT auth, rate limiting, blacklist)
- controllers/auth_controller.go: HTTP handlers for auth flows
- services/auth_service.go: business logic (validate credentials, generate tokens)
- repositories/: data-access layer
- user_repository.go → MySQL via GORM
- token_repository.go → Redis for token storage/blacklist
- models/user.go: user schema
- utils/jwt.go: JWT creation and validation helpers
- docs/: Swagger spec for API documentation

a. Main components
- Clients (Mobile/Web)
- API Gateway / Load Balancer (optional)
- Auth Service (this application)
- HTTP Server (Gin)
- Router
- Middlewares
- Controllers
- Services
- Repositories
- Utils & Config
- MySQL Database
- Redis Cache
- Swagger UI (docs endpoint)

b. Component relationships & data flows
1. Client → HTTP Server (Gin)
2. Router dispatches to middlewares in order:
- RateLimit → Blacklist → JWT Auth
3. Controller → Service
4. Service → Repository
- For user records → MySQL
- For token read/write & blacklist → Redis
5. Service uses Utils (jwt.go) to sign/verify tokens
6. Config module injects DB/Redis connections at startup
7. /docs swagger.json → Swagger UI endpoint

c. Architectural patterns & principles
- Layered (HTTP → Controller → Service → Repository)
- Dependency injection of configs & DB/Cache clients
- Separation of concerns:
- Middlewares handle cross-cutting features (auth, rate limiting)
- Controllers only map HTTP ↔ service calls
- Services encapsulate business rules
- Repositories isolate persistence logic

d. Key technologies & libraries
- Gin (HTTP router)
- GORM + MySQL (ORM)
- Redis client
- golang-jwt/jwt for token handling
- Viper for config management
- swaggo for Swagger generation
- Rate limiter (golang.org/x/time/rate)
- Testify for unit tests

##### Detail is key
- Break the service into as many meaningful sub-components as shown in the file tree
- Boundary where a request or data passes from one layer to another
- Initialization flows (config → DB/Redis client → router setup) if helpful

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Clients\n(Web/Mobile)"]:::external
    APIGW["API Gateway / Load Balancer"]:::external
    Main["Application Entry Point\n(cmd/main.go)"]:::transport
    Config["Configuration Loader\n(configs/config.go)"]:::util
    Router["Router\n(routes/router.go)"]:::transport
    Middlewares["Middlewares\n(auth, rate limit, blacklist)"]:::transport
    Controllers["AuthController\n(controllers/auth_controller.go)"]:::business
    Services["AuthService\n(services/auth_service.go)"]:::business
    UserRepo["UserRepository\n(repositories/user_repository.go)"]:::data
    TokenRepo["TokenRepository\n(repositories/token_repository.go)"]:::data
    Models["User Model\n(models/user.go)"]:::data
    DB["MySQL Database"]:::storage
    Redis["Redis Cache"]:::storage
    JWTUtils["JWT Utils\n(utils/jwt.go)"]:::util
    Swagger["Swagger Docs/UI\n(docs/swagger.yaml)"]:::util

    subgraph "Auth Service"
        subgraph "Transport Layer"
            Router
            Middlewares
        end
        subgraph "Application Layer"
            Controllers
            Services
        end
        subgraph "Data Layer"
            UserRepo
            TokenRepo
            Models
        end
        subgraph "Utilities & Docs"
            Config
            JWTUtils
            Swagger
        end
        DB
        Redis
    end

    Client -->|HTTP Request| APIGW
    APIGW -->|Forwards Request| Main
    Main -->|load configs| Config
    Main -->|init DB client| DB
    Main -->|init Redis client| Redis
    Main -->|setup routes| Router
    Router -->|passes through| Middlewares
    Middlewares -->|dispatch to| Controllers
    Controllers -->|calls| Services
    Services -->|user ops| UserRepo
    Services -->|token ops| TokenRepo
    Services -->|use jwt helpers| JWTUtils
    UserRepo -->|CRUD| DB
    TokenRepo -->|cache & blacklist| Redis
    Client -->|view docs| Swagger

    %% Click Events
    click Main "https://github.com/880831ian/go-auth/blob/20250513/cmd/main.go"
    click Config "https://github.com/880831ian/go-auth/blob/20250513/configs/config.go"
    click Router "https://github.com/880831ian/go-auth/blob/20250513/routes/router.go"
    click Middlewares "https://github.com/880831ian/go-auth/blob/20250513/middlewares/auth_middleware.go"
    click Controllers "https://github.com/880831ian/go-auth/blob/20250513/controllers/auth_controller.go"
    click Services "https://github.com/880831ian/go-auth/blob/20250513/services/auth_service.go"
    click UserRepo "https://github.com/880831ian/go-auth/blob/20250513/repositories/user_repository.go"
    click Models "https://github.com/880831ian/go-auth/blob/20250513/models/user.go"
    click JWTUtils "https://github.com/880831ian/go-auth/blob/20250513/utils/jwt.go"
    click Swagger "https://github.com/880831ian/go-auth/blob/20250513/docs/swagger.yaml"

    %% Styles
    classDef external fill:#f0f4c3,stroke:#333,stroke-width:1px
    classDef transport fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef business fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef data fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef storage fill:#ffcc80,stroke:#333,stroke-width:1px
    classDef util fill:#e0e0e0,stroke:#333,stroke-width:1px
```
