# pilinux/gorest architecture

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

- Interactive diagram: https://gitdiagram.com/pilinux/gorest
- Repository: https://github.com/pilinux/gorest

## Overview

##### Main Components
- Environment & Configuration: Represent the environment variables (.env) and configuration files (in the config directory) as the groundwork for the application’s runtime settings. These include server and email settings, logging configurations, security parameters, and database configurations.
- Routing Layer: Identify the controller, handler, and router folders (e.g., controller/, handler/, example/router/) where incoming HTTP requests are mapped to the appropriate business logic.
- Business Logic / Service Layer: Outline the service directory (service/) which encapsulates business logic such as authentication, postmark email handling, and security operations.
- Database Layer:
- Database connections and migration scripts exist in the database/ folder (and its subfolders such as migrate/ and model/).
- The project supports multiple databases (MySQL, PostgreSQL, SQLite3, Redis, MongoDB) and uses GORM; represent how configuration and model definitions are used to interact with the database.
- Library & Middleware: Highlight the lib/ directory that includes generic utility functions (file handling, encryption, hashing, HTML email rendering) and middleware components (CORS, firewall, JWT processing, twoFA).
- External Integrations: Components like logging (output to logs/ and Sentry integration through lib/middleware/sentry.go) and external configuration (environment variables, email and JWT configuration) should be shown as side services.
- Example Implementation: The example/ folder provides a working instance or blueprint that illustrates how to wire up various components of the system.

##### Relationships and Data Flow
- Requests are directed to Controllers which call the corresponding Handlers. Both controllers and handlers are responsible for receiving request data and passing it to business services as needed.
- Middleware components (from lib/middleware/) wrap around routing and handler logic to enforce CORS, authentication, rate limiting, and request validation.
- The Service layer then processes the logic (e.g., authentication, email verification, two-factor authentication) and interacts with the Database layer via GORM.
- Configuration settings (from config/ and .env) enable and fine-tune interactions (e.g., database connections, logging, security settings).
- Utility libraries (lib/) are used across the application to support encryption, file operations, hashing, etc.
- Error handling, logging, and notifications are piped through appropriate channels (logs directory, Sentry integration).

##### Architectural Patterns & Design Principles
- Separation of concerns: Different folders (config, controller, database, handler, service, lib) indicate a layered design.
- MVC-like structure: While not pure MVC, the project separates request controllers, business logic (services), and data models.
- Modularity: Components are split into independent domains (middleware, encryption, file handling) that are easily testable.
- Extensibility: With directories and example code in place, the design supports rapid prototyping and customization for various project needs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Client Request
    Client("HTTP Request"):::client

    %% Configuration Layer
    subgraph "Configuration Layer"
        Env["Environment (.env.sample)"]:::config
        ConfigFiles["Configuration Files (config/)"]:::config
    end

    %% Routing Layer
    subgraph "Routing Layer"
        GinRouter["Gin Router (example/router/setupRouter.go)"]:::router
        Controllers["Controllers (controller/)"]:::router
        Handlers["Handlers (handler/)"]:::router
    end

    %% Middleware & Libraries Layer
    subgraph "Middleware & Libraries"
        Middleware["Middleware (lib/middleware/)"]:::middleware
        Utilities["Utilities (lib/)"]:::lib
    end

    %% Business Logic / Service Layer
    subgraph "Business Logic"
        Services["Services (service/)"]:::service
    end

    %% Database Layer
    subgraph "Database Layer"
        DBConnection["Database Connection & Config (database/)"]:::database
        Migrations["Migrations (database/migrate/autoMigrate.go)"]:::database
        Models["Models (database/model/)"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        Logs["Logs (logs/README.md)"]:::external
        Sentry["Sentry (lib/middleware/sentry.go)"]:::external
    end

    %% Example Implementation
    subgraph "Example Implementation"
        Example["Example Implementation (example/)"]:::example
    end

    %% Data Flow
    Client -->|"HTTP_Request"| GinRouter
    GinRouter -->|"routes_to"| Controllers
    GinRouter -->|"routes_to"| Handlers
    Controllers -->|"calls"| Middleware
    Handlers -->|"calls"| Middleware
    Middleware -->|"passes_request"| Services
    Utilities -->|"supports"| Services
    Services -->|"interacts_with"| DBConnection
    Services -->|"uses"| Migrations
    Services -->|"uses"| Models
    Services -->|"error_logs"| Logs
    Services -->|"error_reports"| Sentry

    %% Configuration Influence (dotted lines)
    Env ---|"configures"| GinRouter
    Env ---|"configures"| Services
    Env ---|"configures"| DBConnection
    ConfigFiles ---|"configures"| GinRouter
    ConfigFiles ---|"configures"| Services
    ConfigFiles ---|"configures"| DBConnection

    %% Example Blueprint Integration
    Example ---|"blueprint"| GinRouter
    Example ---|"blueprint"| Controllers
    Example ---|"blueprint"| Handlers
    Example ---|"blueprint"| Middleware
    Example ---|"blueprint"| Services
    Example ---|"blueprint"| DBConnection

    %% Click Events
    click Env "https://github.com/pilinux/gorest/blob/main/.env.sample"
    click ConfigFiles "https://github.com/pilinux/gorest/tree/main/config/"
    click GinRouter "https://github.com/pilinux/gorest/blob/main/example/router/setupRouter.go"
    click Controllers "https://github.com/pilinux/gorest/tree/main/controller/"
    click Handlers "https://github.com/pilinux/gorest/tree/main/handler/"
    click Services "https://github.com/pilinux/gorest/tree/main/service/"
    click DBConnection "https://github.com/pilinux/gorest/tree/main/database/"
    click Migrations "https://github.com/pilinux/gorest/blob/main/database/migrate/autoMigrate.go"
    click Models "https://github.com/pilinux/gorest/tree/main/database/model/"
    click Middleware "https://github.com/pilinux/gorest/tree/main/lib/middleware/"
    click Utilities "https://github.com/pilinux/gorest/tree/main/lib/"
    click Logs "https://github.com/pilinux/gorest/blob/main/logs/README.md"
    click Sentry "https://github.com/pilinux/gorest/blob/main/lib/middleware/sentry.go"
    click Example "https://github.com/pilinux/gorest/tree/main/example/"

    %% Styles
    classDef client fill:#f4e842,stroke:#333,stroke-width:2px;
    classDef config fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef router fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef middleware fill:#ff9966,stroke:#333,stroke-width:2px;
    classDef lib fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef service fill:#99ff99,stroke:#333,stroke-width:2px;
    classDef database fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef example fill:#ccffff,stroke:#333,stroke-width:2px;
```
