# go-http-server/core architecture

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

- Interactive diagram: https://gitdiagram.com/go-http-server/core
- Repository: https://github.com/go-http-server/core

## Overview

##### Main Components
- API Layer: The API endpoints and middleware reside in the "api" directory (files like auth_user.go, middleware.go, and server.go) – responsible for handling HTTP requests.
- Command-Line Server: Located in "cmd" (cmd/server.go), this is the application’s entry point that initializes and starts the HTTP server.
- Database Layer: Found in the "internal/database" directory (including sqlc generated code under "sqlc" and raw SQL queries). This layer handles all database interactions with PostgreSQL along with transaction management.
- Worker Processes: In the "worker" directory, these modules handle background processes such as the verification email distribution (distributor, processor, etc.).
- Plugin System: In "plugin/pkg" there are subcomponents for mailing service (mailer) and token generation/verification (token), which encapsulate the core business logic related to sending emails and creating/verifying tokens.
- Utility Layer: Under "utils" (files for configuration, error handling, password management, etc.) which supports common tasks across the system.
- Infrastructure and Configuration: Dockerfile, docker-compose.yml, environment files (.env.example, docker.env) provide deployment configuration and system environment details.

##### Relationships and Interactions
- The HTTP Server (cmd/server.go) receives user requests routed through the API (api folder) where middleware (authentication) intercepts requests.
- API endpoints trigger business logic:
- For registration, after validating user details a new user is created via a transactional database call. A message is enqueued (likely pushed to Redis as implied by the README) for asynchronous processing.
- For login, after user validation, a token is generated using the token plugin (PASETO).
- The Database Layer (internal/database) interacts with the PostgreSQL database (using connection details provided in environment variables, e.g., DB_SOURCE) – executed via sqlc generated methods.
- The Worker Processes (worker directory) pick up tasks from the Redis queue, process email sending (invoking the mailer plugin), and perform logging/reporting functions.
- The plugins for mailer and token are used across the service – these abstract external dependencies and provide a clear separation of concerns.

##### Architectural Patterns & Important Principles
- Modular Design: The separation into directories such as “api”, “internal”, “plugin”, “worker”, and “utils” indicates a decoupled system where each module has a specific responsibility.
- Middleware and Layered Architecture: HTTP request flow is intercepted by middleware that performs tasks like authentication before reaching the business logic.
- Asynchronous Processing: The use of a redis queue to decouple heavy tasks (like sending emails) from the immediate HTTP response, ensuring a responsive user experience.
- Transaction Management: The database interaction (with commit/rollback) is explicitly designed for resilience and data integrity during operations such as registration.
- Extensibility: The plugin approach allows for easy replacement or modification of services like email sending and token generation.

##### Final Touches
- Interaction flows: for instance, illustrating how a registration request triggers a database transaction that, upon success, enqueues a verification email request into Redis, which is later handled by the Worker through the Mailer Plugin.
- Given that this project is designed as a simple backend foundation, the focus should be on clarity around these core components rather than overly detailed internal class/module representations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::client

    %% API Server Subgraph
    subgraph "HTTP API / Authentication Service"
        ServerEntry["Server Entry"]:::apiServer
        API_Module["API Endpoints"]:::api
        Middleware["Auth Middleware"]:::mw
        ServerEntry --> API_Module
        API_Module --> Middleware
    end

    %% Database Layer
    DB["PostgreSQL (internal/database) - sqlc & queries"]:::db

    %% Redis Task Queue
    Redis["Task Queue (Redis)"]:::infra

    %% Background Worker
    Worker["Background Workers (worker)"]:::worker

    %% Plugin Components
    Token["Token Plugin (plugin/pkg/token)"]:::plugin
    Mailer["Mailer Plugin (plugin/pkg/mailer)"]:::plugin

    %% Utility Layer
    Utility["Utility Layer (utils)"]:::util

    %% Containerization & Configuration
    Containerization["Containerization (Docker, docker-compose, env)"]:::infra

    %% Flow Connections
    Client --> ServerEntry
    Middleware -->|"dbCall"| DB
    Middleware -->|"tokenGen"| Token
    Middleware -->|"enqueue"| Redis
    Redis -- "process" --> Worker
    Worker -->|"emailSend"| Mailer

    %% Utility supports multiple components
    Utility --- Middleware
    Utility --- DB
    Utility --- Worker

    %% Containerization orchestrates core services
    Containerization --- ServerEntry
    Containerization --- DB
    Containerization --- Redis

    %% Click Events
    click API_Module "https://github.com/go-http-server/core/tree/product/api"
    click ServerEntry "https://github.com/go-http-server/core/blob/product/cmd/server.go"
    click DB "https://github.com/go-http-server/core/tree/product/internal/database"
    click Worker "https://github.com/go-http-server/core/tree/product/worker"
    click Mailer "https://github.com/go-http-server/core/tree/product/plugin/pkg/mailer"
    click Token "https://github.com/go-http-server/core/tree/product/plugin/pkg/token"
    click Utility "https://github.com/go-http-server/core/tree/product/utils"
    click Containerization "https://github.com/go-http-server/core/blob/product/docker-compose.yml"

    %% Styles
    classDef client fill:#FFE0B3,stroke:#CC7A00,stroke-width:2px;
    classDef api fill:#9EC9FF,stroke:#0D55A3,stroke-width:2px;
    classDef apiServer fill:#B3D9FF,stroke:#0A408A,stroke-width:2px;
    classDef mw fill:#B6E3FF,stroke:#0A5A8E,stroke-width:2px;
    classDef db fill:#FFE699,stroke:#D6A600,stroke-width:2px;
    classDef worker fill:#C2F0C2,stroke:#2E8B57,stroke-width:2px;
    classDef plugin fill:#F9DAD0,stroke:#C44D58,stroke-width:2px;
    classDef util fill:#E8E8E8,stroke:#777777,stroke-width:2px;
    classDef infra fill:#FFD2D2,stroke:#D9534F,stroke-width:2px;
```
