# uberswe/golang-base-project architecture

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

- Interactive diagram: https://gitdiagram.com/uberswe/golang-base-project
- Repository: https://github.com/uberswe/golang-base-project

## Overview

##### Project Type and Purpose
- This is a minimal full-stack web application template, written in Go. Its primary purpose is to provide a foundation with built-in user authentication including login, registration, user activation, password management, and an admin dashboard.
- It uses Gin as a web framework, GORM for database interactions, and integrates a modern frontend asset pipeline (using Webpack, SASS, and Bootstrap) to ensure small and optimized page loads.

##### Project File Structure to Extract Major Components
- Back End:
- The Go code under directories like /cmd/base (for the entry point), /routes (defining the HTTP endpoints), /middleware (managing authentication, sessions, caching, etc.), /models (defining database models), /config, and other packages like email, lang, and text.
- The main.go files spread across the project (in the project root, as well as in various packages) indicate that the Go backend is modularized.
- Front End:
- The /src directory holds SCSS and JavaScript files that are compiled via tools (Webpack and sass-loader) into the /dist folder.
- /dist also contains HTML templates that form the view layer.
- Database:
- The project uses GORM to support different SQL databases. Also note the configuration for a quick setup with an in-memory SQLite database or other databases via environment variables.
- Deployment/CI:
- Dockerfile and docker-compose.yml files for containerized deployment.
- GitHub Actions workflows (in .github/workflows) for automated deployment.
- Internationalization:
- Files in the /lang directory and .toml translation files indicate support for translations using go-i18n.

##### Key Architectural Components
a. Frontend Layer:
- “Static Assets and Templates” component: Represent the compiled assets in /dist (HTML templates, CSS, JS).
- “Asset Build Pipeline”: Show a pipeline from /src (with SCSS/JS) through Webpack (and tools like PurgeCss) that produces the assets.
b. Back End Layer:
- “HTTP Server / Router”: Based on Gin and encapsulated in main.go and routes package.
- “Middleware Stack”: Represent the various middleware components handling authentication, sessions, caching, and throttling (found in /middleware).
- “Business Logic and Controllers”: Represented by the route handlers and corresponding logic spread across /routes and other supporting packages.
- “Data Layer”: The database models (in /models) and the use of GORM to handle database operations.
- “Email Service”: The email package providing email functionality (activation, notifications) and using SMTP parameters from environment variables.
- “Internationalization Service”: Handled in the lang package and associated TOML files.
c. Supporting and External Services:
- “Database Server”: External SQL database (SQLite, MySQL, PostgreSQL, etc.) as configured via env variables.
- “SMTP Server”: External email service (using providers like Mailtrap for development).
- “Containerization & Deployment”: Docker components, docker-compose, and the GitHub Actions deployment workflow.
- “Configuration”: Representation of environment variables that configure each component (ports, cookie secrets, cache settings, etc.).

##### Relationships and Interactions
- From the HTTP Server, display the separation into different route controllers (e.g., login, logout, registration, admin dashboard, etc.).
- “Business Logic” to the “Database Layer” (models/GORM) to represent data read/write operations.
- That static file requests are served from the “Static Assets and Templates” component.
- Interaction from the “Email Service” to the external “SMTP Server” for sending emails.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that controllers, middleware, and services are separated into distinct packages.
- MVC-like separation: The routing and middleware handle requests (Controller), models represent data (Model), and the compiled templates represent the View.
- Containerization: Indicate that the project is designed to run in Docker containers and is orchestrated via docker-compose.
- CI/CD: Represent how the GitHub Actions workflow automates deployment.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Interaction
    Browser["User Browser"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        Static["Static Assets and Templates"]:::frontend
        Pipeline["Asset Build Pipeline"]:::frontend
    end

    %% Back End Layer
    subgraph "Back End Layer"
        HTTP["HTTP Server / Router (Gin)"]:::backend
        Middleware["Middleware Stack"]:::backend
        Controllers["Business Logic and Controllers"]:::backend
        Data["Data Layer (Models/GORM)"]:::backend
        Email["Email Service"]:::backend
        Intl["Internationalization Service"]:::backend
    end

    %% Supporting & External Services
    subgraph "Supporting & External Services"
        DB["Database Server (SQL)"]:::external
        SMTP["SMTP Server"]:::external
        Config["Configuration / Env Variables"]:::config
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        Docker["Containerization & Deployment"]:::deployment
        CI["CI/CD (GitHub Actions)"]:::deployment
    end

    %% Connections
    Browser -->|"HTTPRequest"| HTTP
    HTTP -->|"ProcessRequest"| Middleware
    Middleware -->|"Delegate"| Controllers
    Controllers -->|"DataOps"| Data
    Data -->|"Queries"| DB
    HTTP -->|"ServeStatic"| Static
    Pipeline -->|"BuildsAssets"| Static
    Controllers -->|"SendEmail"| Email
    Email -->|"Uses"| SMTP
    Controllers -->|"FetchTranslations"| Intl

    Config -->|"Sets"| HTTP
    Config -->|"Sets"| Data
    Config -->|"Sets"| Email
    Config -->|"Sets"| Intl
    CI -->|"TriggersBuild"| Docker
    Config -->|"ProvidesSettings"| Docker

    %% Click Events for Component Mapping
    click HTTP "https://github.com/uberswe/golang-base-project/blob/main/cmd/base/main.go"
    click HTTP "https://github.com/uberswe/golang-base-project/tree/main/routes/"
    click Middleware "https://github.com/uberswe/golang-base-project/tree/main/middleware/"
    click Controllers "https://github.com/uberswe/golang-base-project/tree/main/routes/"
    click Data "https://github.com/uberswe/golang-base-project/tree/main/models/"
    click Email "https://github.com/uberswe/golang-base-project/blob/main/email/main.go"
    click Intl "https://github.com/uberswe/golang-base-project/tree/main/lang/"
    click Intl "https://github.com/uberswe/golang-base-project/blob/main/active.en.toml"
    click Intl "https://github.com/uberswe/golang-base-project/blob/main/active.sv.toml"
    click Static "https://github.com/uberswe/golang-base-project/tree/main/dist/assets/"
    click Static "https://github.com/uberswe/golang-base-project/tree/main/dist/templates/"
    click Pipeline "https://github.com/uberswe/golang-base-project/tree/main/src/"
    click Pipeline "https://github.com/uberswe/golang-base-project/blob/main/webpack.config.js"
    click Docker "https://github.com/uberswe/golang-base-project/tree/main/Dockerfile"
    click Docker "https://github.com/uberswe/golang-base-project/blob/main/docker-compose.yml"
    click Docker "https://github.com/uberswe/golang-base-project/blob/main/.github/workflows/deploy.yml"
    click Config "https://github.com/uberswe/golang-base-project/tree/main/config/"
    click Config "https://github.com/uberswe/golang-base-project/blob/main/env.go"

    %% Styling
    classDef client fill:#ffe6e6,stroke:#cc0000,stroke-width:2px
    classDef frontend fill:#e6f7ff,stroke:#0073e6,stroke-width:2px
    classDef backend fill:#e6ffe6,stroke:#00a300,stroke-width:2px
    classDef external fill:#fff5cc,stroke:#e6ac00,stroke-width:2px
    classDef config fill:#f2f2f2,stroke:#b3b3b3,stroke-width:2px
    classDef deployment fill:#f0e6ff,stroke:#8000ff,stroke-width:2px
```
