# jpengineer/golyn architecture

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

- Interactive diagram: https://gitdiagram.com/jpengineer/golyn
- Repository: https://github.com/jpengineer/golyn

## Overview

##### Project type and purpose
- The Golyn project is a custom-built, multi-site web server written in Golang. Its main purpose is to host and manage multiple websites – with a strong emphasis on hosting a personal portfolio – by dynamically loading site-specific configurations. It uses the Gin framework for handling HTTP requests and integrates various internal packages like middlewares, modules, routes, and database components.

##### File structure
- Key directories include:
- cmd – Contains the main entry point (golyn.go) to start the server.
- config – Holds global configuration files and site-specific configuration files (*.conf) for both the server and individual sites.
- app – Contains core application logic and shared components.
- internal – Contains handlers, utility functions, and important server routines like shutdown and error handling.
- middlewares – Consists of custom middlewares managing aspects like authentication, logging, caching, CORS, and IP restrictions.
- modules – Contains additional domain-specific logic (e.g., authentication modules for login and token management).
- routes – Manages the API versioning and routing (public/private and virtual hosts).
- database – Provides database interaction modules including instance management, queries, and token repository functions.
- certificates – Stores certificate files for TLS/SSL support (with groups per site, e.g., golyn, kayak, portal.golyn).
- docker – Provides Docker configurations for the PostgreSQL database and related shell scripts.
- sites and builds – Hold the static files and assets served by the server.
- This well-organized file tree shows a modular design with clear separation between configuration, business logic, request handling, static site content, and deployment scripts.

##### README for additional insights
- The README reinforces the multi-site capability and emphasizes configurable and secure hosting via custom .conf files.
- The README outlines the tech stack (Golang and the Gin framework), purpose (hosting personal portfolios and multiple sites), and detailed configuration mechanisms.
- It also hints at extendability (for future related modules such as authentication and database connectivity).

##### Main components to illustrate
a. Main Server Process:
- cmd/golyn.go: The primary executable that initializes and starts the Golyn server.
b. Configuration Management:
- config/ – Global server configuration (server settings in web_server.conf) and site-specific configurations (in config/sites).
- certificates/ – TLS certificate and key management for secure HTTPS connections.
c. Core Business Logic:
- app/ – Central application logic and shared components.
- internal/ – Request handlers, server lifecycle management, error templates, and utility functions.
- modules/ – Modules providing enhanced functionalities such as authentication.
- routes/ – Defines routing (API versions, public/private endpoints, virtual hosts) and orchestrates request flow.
d. Middleware:
- middlewares/ – Middleware components handling logging, CORS, secure routing, IP restrictions, caching, and custom error handling.
e. Data Persistence and External Dependencies:
- database/ – Manages interactions with the database (with a planned or integrated PostgreSQL connection).
- docker/ – Contains Dockerfiles and scripts for database deployment; establishes external dependency management.
f. Static Content Serving:
- sites/ and builds/ – Serve static webpages, assets (JS, CSS, images), and error pages.

##### Relationships and interactions between components
- Incoming HTTP requests first hit the server via the entry point in cmd/golyn.go.
- The server loads global and site-specific configuration files located in the config directory.
- Requests pass through a chain of middlewares (authentication, logging, CORS, etc.) in the middlewares directory.
- The routing system (routes/) directs requests to the appropriate handler functions located within internal/handlers.
- Handlers may interact with the business logic in app/ or modules (such as authentication in modules/auth) and may also query / update the database layer.
- Static content is served from the sites folder, while builds provide prepackaged deployments.
- Certificates from the certificates folder are used to enable secure (HTTPS) communications.
- An optional external database (documented in the docker and database directories) can be illustrated as a separately managed dependency.

##### Highlighting architectural patterns and technologies
- Modular separation of components (MVC-like design), separation between configuration and logic, and middleware-based request processing.
- Technologies include Golang, the Gin framework, and custom logging via the Logger package.
- Usage of Docker for data persistence (PostgreSQL) and potential TLS/SSL integration.

##### Specific elements
- Clear labels for each component (e.g., “Main Server”, “Configuration Manager”, “Middleware”, “Router & Handlers”, “Static Site Content”, “Certificate Manager”, “Database”).
- The flow of requests from client → server entry point → middleware stack → route/handler selection → response generation.
- The dependency of the server on configuration files and external certificates.
- The interaction of certain modules (like database queries) within the request handling process.
- Core executable logic (cmd, app, internal)
- Support systems (config, certificates, docker, database)
- Middleware and routing components (middlewares, routes)
- Static assets (sites, builds)

##### Final advice
- Focus not only on the logical separation of code (configuration vs. request handling vs. auxiliary services) but also on how these components interact during a typical request lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client Request"]:::client

    %% Core Server Process
    Server["Main Server (cmd/golyn.go)"]:::server
    Client -->|"HTTP_Request"| Server

    %% Configuration Management
    Config["Configuration Manager"]:::config
    Config_Global["Global & Site-Specific Configurations (config/)"]:::config
    Config_Cert["TLS/SSL Certificate Manager (certificates/)"]:::config
    Server -->|"Load_Config"| Config_Global
    Server -->|"Load_Cert"| Config_Cert

    %% Middleware Processing
    Middleware["Middleware (middlewares/)"]:::middleware
    Server -->|"Processes"| Middleware

    %% Routing and Handlers
    Routing["Routing & Handlers (routes/, internal/)"]:::routing
    Middleware -->|"Routes_To"| Routing

    %% Core Business Logic
    Business["Core Business Logic"]:::business
    AppLogic["Application Logic (app/)"]:::business
    Modules["Domain Modules (modules/auth)"]:::business
    Routing -->|"Invokes"| AppLogic
    Routing -->|"Invokes"| Modules

    %% Data Persistence and External Dependencies
    Data["Data Persistence"]:::db
    Database["Database Management (database/)"]:::db
    Docker["Docker & External DB Setup (docker/)"]:::db
    Modules -->|"DB_Queries"| Database
    Database -->|"Setup_By"| Docker

    %% Static Content Serving
    Static["Static Content Serving"]:::static
    Sites["Live Static Sites (sites/)"]:::static
    Builds["Pre-packaged Builds (builds/)"]:::static
    Server -->|"Serves_Static"| Sites
    Sites -->|"Packaged_In"| Builds

    %% Click Events
    click Server "https://github.com/jpengineer/golyn/blob/main/cmd/golyn.go"
    click Config_Global "https://github.com/jpengineer/golyn/tree/main/config/"
    click Config_Cert "https://github.com/jpengineer/golyn/tree/main/certificates/"
    click AppLogic "https://github.com/jpengineer/golyn/blob/main/app/application.go"
    click Modules "https://github.com/jpengineer/golyn/blob/main/modules/auth/login.go"
    click Middleware "https://github.com/jpengineer/golyn/tree/main/middlewares/"
    click Routing "https://github.com/jpengineer/golyn/tree/main/routes/api/v1"
    click Database "https://github.com/jpengineer/golyn/blob/main/database/database.go"
    click Docker "https://github.com/jpengineer/golyn/tree/main/docker/"
    click Sites "https://github.com/jpengineer/golyn/blob/main/sites/golyn/index.html"
    click Builds "https://github.com/jpengineer/golyn/tree/main/builds/Golyn"

    %% Styles
    classDef client fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef server fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef config fill:#d2b4de,stroke:#7d3c98,stroke-width:2px;
    classDef middleware fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef routing fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef business fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef db fill:#f7dc6f,stroke:#b7950b,stroke-width:2px;
    classDef static fill:#d4efdf,stroke:#239b56,stroke-width:2px;
```
