# nerijusdu/vesa architecture

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

- Interactive diagram: https://gitdiagram.com/nerijusdu/vesa
- Repository: https://github.com/nerijusdu/vesa

## Overview

##### Main Components
- Backend Server:
- Core executable (main.go) that initializes the server.
- Packages that serve discrete responsibilities:
– pkg/config: Handles configuration management.
– pkg/data: Manages data models and interactions (e.g., apps, auth, jobs, projects, templates, logs, traefik configuration).
– pkg/dockerctrl: Contains the Docker API integration components such as container, network, and client operations.
– pkg/runner: Likely responsible for running jobs or tasks.
– pkg/web: Implements the RESTful API endpoints (e.g., for apps, containers, projects, networks, templates, and authentication) that the frontend will use.
– pkg/util: General utility functions (e.g., for encoding, security, randomness).
- Frontend Application:
- Located in the “web” directory (along with subdirectories like src, components, and features).
- Built using React, TypeScript, and Vite (as per vite.config.ts and TypeScript configuration files).
- Static Assets & Templates:
- The “public” folder holds static assets (such as the main index.html and built JS files).
- “templates” folder (e.g., traefik.json) for predefined container configurations.
- External Integrations & Infrastructure:
- Docker daemon: The backend interacts with Docker via the dockerctrl package.
- Traefik: As evident from files like pkg/data/traefik.go and templates/traefik.json, it is used for routing and managing SSL certificates with LetsEncrypt.
- GitHub Actions: Configured for automated releases (note the github-actions/release.yml), enabling CI/CD pipelines.
- Systemd Service: Instructions for auto-start on boot indicate integration with the underlying OS init system.

##### Out the Relationships & Interactions
- The Browser (User Interface):
- Users interact with the React-based web frontend.
- The frontend communicates with the Go backend via REST API calls.
- The Go Backend:
- API Endpoints (located in pkg/web) expose functionality for managing Docker containers, networks, and more.
- It calls into lower-level packages:
▪ pkg/dockerctrl interacts with the Docker daemon to perform container operations.
▪ pkg/data interacts with persistent configuration or data models.
▪ pkg/runner may trigger scheduled or on-demand tasks.
- The configuration (pkg/config) sets up the necessary environment at startup.
- External Services:
- Docker daemon serves as the actual engine executing container operations.
- Traefik and LetsEncrypt are leveraged to manage domain routing and secure certificates.
- GitHub Actions handle automated deployments and releases.

##### Architectural Patterns & Principles
- Separation of Concerns: Clear demarcation between frontend (user interface) and backend (API server and business logic).
- Layered Architecture: Each package in the backend addresses a specific concern (configuration, data management, docker integration, etc.).
- Extensibility: The design supports additional features (e.g., volumes, secrets, CLI tools) via clear module boundaries.
- API-driven Communication: The frontend communicates with the backend via REST interfaces, promoting a decoupled system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Browser"]:::external
        Frontend["Frontend (React App)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BackendMain["Backend Main Server (Go)"]:::backend
        APIEndpoints["API Endpoints (pkg/web)"]:::backend
        ConfigMgr["Configuration Manager (pkg/config)"]:::backend
        DataModels["Data Models & Services (pkg/data)"]:::backend
        DockerCtrl["Docker Controller (pkg/dockerctrl)"]:::backend
        TaskRunner["Task Runner (pkg/runner)"]:::backend
        UtilModules["Utility Modules (pkg/util)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        StaticAsset["Static Asset Server (public)"]:::external
        DockerDaemon["Docker Daemon"]:::external
        Traefik["Traefik/SSL (Let'sEncrypt)"]:::external
        Templates["Templates (templates/traefik.json)"]:::external
        CI_CD["CI/CD Pipeline (GitHub Actions)"]:::pipeline
        Systemd["Systemd Service"]:::external
    end

    %% Connections between Frontend, Backend, and External Services
    Browser -->|"loads"| Frontend
    Frontend -->|"REST_API_calls"| APIEndpoints
    StaticAsset -->|"serves_assets"| Frontend

    BackendMain --> APIEndpoints
    BackendMain --> ConfigMgr
    BackendMain --> DataModels
    BackendMain --> DockerCtrl
    BackendMain --> TaskRunner
    BackendMain --> UtilModules

    APIEndpoints -->|"utilizes"| ConfigMgr
    APIEndpoints -->|"utilizes"| DataModels
    APIEndpoints -->|"triggers"| TaskRunner
    APIEndpoints -->|"calls"| DockerCtrl
    APIEndpoints -->|"routes"| Traefik

    DockerCtrl -->|"calls"| DockerDaemon
    ConfigMgr -->|"reads"| Templates

    CI_CD -->|"deploys"| BackendMain
    Systemd -->|"starts"| BackendMain

    %% Click Events
    click BackendMain "https://github.com/nerijusdu/vesa/blob/main/main.go"
    click ConfigMgr "https://github.com/nerijusdu/vesa/blob/main/pkg/config/config.go"
    click DataModels "https://github.com/nerijusdu/vesa/tree/main/pkg/data"
    click DockerCtrl "https://github.com/nerijusdu/vesa/tree/main/pkg/dockerctrl"
    click TaskRunner "https://github.com/nerijusdu/vesa/blob/main/pkg/runner/runner.go"
    click UtilModules "https://github.com/nerijusdu/vesa/tree/main/pkg/util"
    click APIEndpoints "https://github.com/nerijusdu/vesa/tree/main/pkg/web"
    click Frontend "https://github.com/nerijusdu/vesa/tree/main/web"
    click StaticAsset "https://github.com/nerijusdu/vesa/tree/main/public"
    click Templates "https://github.com/nerijusdu/vesa/blob/main/templates/traefik.json"
    click CI_CD "https://github.com/nerijusdu/vesa/blob/main/github-actions/release.yml"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef pipeline fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
```
