# nisibz/go-auth-tests architecture

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

- Interactive diagram: https://gitdiagram.com/nisibz/go-auth-tests
- Repository: https://github.com/nisibz/go-auth-tests

## Overview

##### Project Type and Purpose
- This is a Go-based RESTful API focused on user authentication and management. It demonstrates user registration, login (JWT-based), protected routes, profile CRUD, and secure password handling (bcrypt), all backed by MongoDB.

##### File Structure Analysis
- **cmd/http/main.go**: Entry point, bootstraps the HTTP server.
- **internal/adapter**: Adapter layer implementing configuration loading, HTTP handlers (Gin routes), logging (slog), and MongoDB data access (models + repositories).
- **internal/core**: Core business logic organized by Clean/Hexagonal Architecture:
- **domain**: Core entities (User) and domain-level errors.
- **port**: Interfaces (inbound and outbound ports for auth and user workflows).
- **service**: Implementations of business use-cases (registration, login, user management).
- **util**: JWT and bcrypt utilities.
- **Infrastructure**:
- **Dockerfile**, **docker-compose.yml**: Containerization & orchestration.
- **.env.example**: Environment variable template.
- **go.mod**, **go.sum**: Dependency management.

##### Key Components
a. **Client**: External caller (Postman, UI, other services) sending HTTP requests.
b. **HTTP Server (Gin)**:
- Listens on configured port.
- Delegates to middleware (JWT validation) and request handlers.
c. **Configuration Loader**: Reads environment variables (.env) and provides typed config objects.
d. **Router & Middleware**:
- Defines `/api/auth` and `/api/users` endpoints.
- Applies logging and JWT-based auth middleware.
e. **Handler Layer**: Transforms HTTP requests into Core port calls (AuthPort, UserPort).
f. **Service Layer (Core)**:
- Implements registration, login, and user CRUD.
- Uses JWT util to sign/verify tokens.
- Uses bcrypt util to hash/compare passwords.
g. **Repository Layer**:
- MongoDB connection manager.
- UserRepository implements persistence port.
- Converts between domain.User and MongoDB models.
h. **MongoDB**: External database for user data.
i. **Logger (slog)**: Structured logging across all layers.

##### Relationships and Data Flow
1. Client → HTTP Server (request)
2. HTTP Server → Middleware (logging, JWT validation)
3. Middleware (JWT validated) → Handler
4. Handler → Core Service via defined port interface
5. Service → Util (bcrypt for passwords, JWT for tokens)
6. Service → Repository (CRUD operations)
7. Repository ↔ MongoDB
8. Response bubbles back up: DB → Repository → Service → Handler → HTTP Server → Client

##### Architectural Patterns and Principles
- **Clean/Hexagonal Architecture**: Core business logic is isolated behind port interfaces; adapters plug in for I/O.
- **Single Responsibility**: Config, logging, HTTP handling, business logic, and persistence each in separate packages.
- **Dependency Inversion**: Core defines interfaces; adapters implement them.
- **Layered Security**: Password hashing at service; JWT-based route protection via middleware.

##### Putting It All Together
- To its right, stack **HTTP Server** (Gin) and beneath it the **Router & Middleware**.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client"]:::external

    %% Infrastructure
    ConfigLoader["Config Loader\n(internal/adapter/config/config.go)"]:::infra
    Logger["Logger (slog)\n(internal/adapter/logger/slog.go)"]:::infra

    %% HTTP Layer
    HTTPServer["HTTP Server (Gin)\n(cmd/http/main.go)"]:::http
    RouterMiddleware["Router & Middleware\n(internal/adapter/handler/http/router.go,\ninternal/adapter/handler/http/middleware.go)"]:::http

    %% Handler Layer
    AuthHandler["AuthHandler\n(internal/adapter/handler/http/auth.go)"]:::http
    UserHandler["UserHandler\n(internal/adapter/handler/http/user.go)"]:::http

    %% Core Domain & Ports
    subgraph "Core Domain" 
        direction TB
        DomainEntities["Domain Entities & Errors\n(internal/core/domain/user.go,\ninternal/core/domain/error.go)"]:::core
    end

    subgraph "Port Interfaces"
        direction TB
        AuthPort["AuthPort Interface\n(internal/core/port/auth.go)"]:::core
        UserPort["UserPort Interface\n(internal/core/port/user.go)"]:::core
    end

    %% Service Layer
    AuthService["AuthService\n(internal/core/service/auth.go)"]:::core
    UserService["UserService\n(internal/core/service/user.go)"]:::core

    %% Utilities
    JWTUtil["JWT Util\n(internal/core/util/jwt.go)"]:::util
    BcryptUtil["Bcrypt Util\n(internal/core/util/bcrypt.go)"]:::util

    %% Repository & Storage
    subgraph "MongoDB Storage"
        direction TB
        MongoDB[(MongoDB)]:::db
    end
    UserRepository["UserRepository\n(internal/adapter/storeages/mongodb/repository/user.go)"]:::repo

    %% Connections
    Client -->|"HTTP Request"| HTTPServer
    HTTPServer -->|"Initialize Routes"| RouterMiddleware
    RouterMiddleware -->|"Route to Auth"| AuthHandler
    RouterMiddleware -->|"Route to Users"| UserHandler

    AuthHandler -->|"calls AuthPort"| AuthPort
    UserHandler -->|"calls UserPort"| UserPort

    AuthPort -->|"implemented by"| AuthService
    UserPort -->|"implemented by"| UserService

    AuthService -->|"uses util"| JWTUtil
    AuthService -->|"uses util"| BcryptUtil
    UserService -->|"uses util"| BcryptUtil

    AuthService -->|"calls Repository"| UserRepository
    UserService -->|"calls Repository"| UserRepository

    UserRepository -->|"Query users collection"| MongoDB

    %% Config & Logger dependencies
    ConfigLoader --> HTTPServer
    ConfigLoader --> RouterMiddleware
    ConfigLoader --> AuthHandler
    ConfigLoader --> UserHandler
    ConfigLoader --> AuthService
    ConfigLoader --> UserService
    ConfigLoader --> UserRepository

    Logger --> HTTPServer
    Logger --> RouterMiddleware
    Logger --> AuthHandler
    Logger --> UserHandler
    Logger --> AuthService
    Logger --> UserService
    Logger --> UserRepository

    %% Styles
    classDef http fill:#D0E7FF,stroke:#4A90E2,stroke-width:2px
    classDef core fill:#E6F9E0,stroke:#34A853,stroke-width:2px
    classDef repo fill:#FFEBCC,stroke:#FB8C00,stroke-width:2px
    classDef util fill:#F3F4F5,stroke:#6B7280,stroke-width:2px
    classDef infra fill:#F0F0FF,stroke:#7C4DFF,stroke-width:2px
    classDef db fill:#FFEFEF,stroke:#D32F2F,stroke-width:2px
    classDef external fill:#E8E8E8,stroke:#888888,stroke-width:2px

    %% Click Events
    click HTTPServer "https://github.com/nisibz/go-auth-tests/blob/main/cmd/http/main.go"
    click ConfigLoader "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/config/config.go"
    click RouterMiddleware "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/handler/http/router.go"
    click RouterMiddleware "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/handler/http/middleware.go"
    click AuthHandler "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/handler/http/auth.go"
    click UserHandler "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/handler/http/user.go"
    click Logger "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/logger/slog.go"
    click DomainEntities "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/domain/user.go"
    click DomainEntities "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/domain/error.go"
    click AuthPort "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/port/auth.go"
    click UserPort "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/port/user.go"
    click AuthService "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/service/auth.go"
    click UserService "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/service/user.go"
    click JWTUtil "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/util/jwt.go"
    click BcryptUtil "https://github.com/nisibz/go-auth-tests/blob/main/internal/core/util/bcrypt.go"
    click UserRepository "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/storeages/mongodb/repository/user.go"
    click MongoDB "https://github.com/nisibz/go-auth-tests/blob/main/internal/adapter/storeages/mongodb/db.go"
```
