# quanluon/go-base-authenication architecture

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

- Interactive diagram: https://gitdiagram.com/quanluon/go-base-authenication
- Repository: https://github.com/quanluon/go-base-authenication

## Overview

##### Project Type and Purpose
- This is a back-end API server for user authentication, authorization, and role-based access control (RBAC).
- Key features include JWT-based authentication, refresh tokens, password hashing, error handling, logging, and various middlewares.
- The target audience is those requiring a robust and scalable authentication system in Go, integrating with a Postgres database.

##### File Structure to Identify Main Components
- Entry Point: The file main.go is the application’s starting point.
- Internal Package Structure: Under the "internal" folder, separate packages represent:
- Controllers (internal/controllers) – Handle HTTP requests for authentication, user registration, and management.
- Services (internal/services) – Encapsulate business logic such as JWT handling, authentication flows, and role management.
- Repositories (internal/repositories) – Abstract database operations.
- Database (internal/db) – Contains database connections, migrations (in migrations folder), and SQL queries (in queries folder).
- Routes (internal/routes) – Define the API endpoints mapping to respective controllers.
- Middlewares (internal/middlewares) – Manage authentication and authorization checks.
- Other Components:
- Constants and DTOs: Used to standardize error messages, permissions, and data transfer objects.
- Cron folder: Contains scheduled tasks logic, which is likely run periodically (log.go).
- Utility Functions: Provided in the utils folder for common response formatting, error handling, and request processing.
- Configuration: .env and .env.example for environment-specific settings and Dockerfile/Makefile for deployment and orchestration.

##### Main Components and Their Relationships
a. Front Controller & Routing:
- The API gateway/controller (set up in main.go) configures routes via the internal/routes package.
- Routes then map to corresponding controllers which handle HTTP requests.
b. Controllers:
- Each controller (in internal/controllers) receives requests, extracts data (using DTOs), and forwards it to the respective service.
c. Services:
- Services encapsulate the business rules (e.g., authentication, JWT token management, role checks).
- They often call the repository layer for database interactions.
d. Repositories and Database:
- The repositories layer (internal/repositories) abstracts CRUD operations.
- Database connectivity and model generation are managed in internal/db using sqlc-generated code, along with migrations.
e. Middlewares:
- Middleware components (in internal/middlewares) intercept requests to enforce security (authentication and authorization) before reaching the controllers.
f. Scheduled Tasks:
- The cron folder (cron/log.go) executes periodic tasks like logging or maintenance operations.

##### Architectural Patterns and Technologies to Highlight
- Clean Architecture: Emphasize separation of concerns between controllers, services, repositories, and database layers.
- API Routing: Using internal/routes with clear HTTP endpoint definitions.
- Database Management: Integration with Postgres, using pgx as the DB client, sqlc for ORM-like functionality, and goose for migration management.
- Authentication & Authorization: JWT services, refresh token management, and middleware enforcement.
- Development and Deployment: Dockerfile, Makefile, and CI/CD workflows under .github/workflows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Request
    CR["Client Request"]:::external

    %% Application Layer
    subgraph "Application Layer"
        A["main.go"]:::entry
        B["API Routing"]:::routing
        C["Middlewares"]:::middleware
        D["Controllers"]:::controller
        E["Services"]:::service
        F["Repositories"]:::repository
        G["Database (Postgres)"]:::database
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        H["DTOs"]:::dto
        I["Constants"]:::constant
        J["Utility Functions"]:::util
    end

    %% Infrastructure Components
    subgraph "Infrastructure"
        K["Cron Jobs"]:::cron
        L["Deployment & Config"]:::deploy
    end

    %% Flow Connections
    CR -->|"calls"| A
    A -->|"configuresRoutes"| B
    B -->|"invokesMiddleware"| C
    C -->|"routesTo"| D
    D -->|"triggers"| E
    E -->|"accessesData"| F
    F -->|"performsCRUD"| G
    %% Supporting Modules Usage
    D -->|"usesDTOs"| H
    D -->|"utilizes"| J
    E -->|"usesConstants"| I
    E -->|"utilizes"| J
    %% Deployment Initialization
    A -->|"loadsConfig"| L
    %% Cron Job Independent Flow
    K -->|"runsTasksUsing"| J

    %% Click Events
    click A "https://github.com/quanluon/go-base-authenication/blob/main/main.go"
    click B "https://github.com/quanluon/go-base-authenication/tree/main/internal/routes"
    click C "https://github.com/quanluon/go-base-authenication/tree/main/internal/middlewares"
    click D "https://github.com/quanluon/go-base-authenication/tree/main/internal/controllers"
    click E "https://github.com/quanluon/go-base-authenication/tree/main/internal/services"
    click F "https://github.com/quanluon/go-base-authenication/tree/main/internal/repositories"
    click G "https://github.com/quanluon/go-base-authenication/tree/main/internal/db"
    click H "https://github.com/quanluon/go-base-authenication/tree/main/internal/dto"
    click I "https://github.com/quanluon/go-base-authenication/tree/main/internal/constants"
    click J "https://github.com/quanluon/go-base-authenication/tree/main/utils"
    click K "https://github.com/quanluon/go-base-authenication/tree/main/cron"
    click L "https://github.com/quanluon/go-base-authenication/tree/main/Dockerfile"

    %% Class Definitions for Colors
    classDef entry fill:#add8e6,stroke:#000,stroke-width:1.5px;
    classDef routing fill:#90ee90,stroke:#000,stroke-width:1.5px;
    classDef middleware fill:#ffeb99,stroke:#000,stroke-width:1.5px;
    classDef controller fill:#ffcccb,stroke:#000,stroke-width:1.5px;
    classDef service fill:#f0e68c,stroke:#000,stroke-width:1.5px;
    classDef repository fill:#dda0dd,stroke:#000,stroke-width:1.5px;
    classDef database fill:#d3d3d3,stroke:#000,stroke-width:1.5px;
    classDef dto fill:#40e0d0,stroke:#000,stroke-width:1.5px;
    classDef constant fill:#ffc0cb,stroke:#000,stroke-width:1.5px;
    classDef util fill:#deb887,stroke:#000,stroke-width:1.5px;
    classDef cron fill:#da70d6,stroke:#000,stroke-width:1.5px;
    classDef deploy fill:#afeeee,stroke:#000,stroke-width:1.5px;
    classDef external fill:#fffacd,stroke:#000,stroke-width:1.5px;
```
