# sahsanu/hestiacp architecture

> Architecture diagram of the GitHub repository sahsanu/hestiacp, 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/sahsanu/hestiacp
- Repository: https://github.com/sahsanu/hestiacp

## Overview

##### Main Components
- User Interfaces:
– Web Interface: Represented by the “web” directory (the PHP/HTML/CSS/JS UI, including login, dashboard, and all user-facing pages).
– Command-Line Interface: The “bin” directory scripts (e.g., v-add-*, v-change-*, v-list-* commands) that allow administrators to perform system management tasks.
- Core Application Logic:
– PHP Application Engine: Located in “web/src/app/…”, which contains the core classes, business logic, and the command routing mechanism used by the control panel.
– API Endpoints: Files in “web/api” and the various “install/common/api” modules which expose programmatic ways to interact with billing, mail, and DNS endpoints.
- Deployment and Installation:
– Installer & Upgrade Scripts: Found under “install” (including subdirectories for different Linux distributions and package definitions) and upgrade versions in “install/upgrade” to perform installation, configuration, and updates.
– Packaging Components: “src/deb” and “install/deb” hold the Debian packaging/control files to integrate with OS-native service managers.
- Underlying Server Services (External/OS components):
– Web Servers: Apache2 and NGINX (with configuration files under “install/deb/apache2”, “install/deb/nginx”).
– Database Servers: MariaDB/MySQL and PostgreSQL (config files under “install/deb/mysql” and “install/deb/postgresql”).
– DNS Service: Bind, with clustering capabilities (configs under “install/deb/bind” and DNS templates in “install/common/templates/dns”).
– Mail Services: Dovecot, Exim, Roundcube, ClamAV, SpamAssassin (found in “install/common/dovecot”, “install/deb/exim”, “install/deb/roundcube” respectively).
– Firewall and Security: Integration of iptables/ipset, fail2ban, and additional security scripts.
– SSL and Certificate Management: Let’s Encrypt integration, as seen from scripts like “v-add-letsencrypt-domain” and configuration templates.
- Infrastructure for CI/Testing & Documentation:
– CI/CD Configuration: GitHub workflows, Drone pipelines, linting, and test scripts (directories like “.github”, “.drone.yml”, “test”).
– Documentation: Extensive documentation and guides under “docs” that explain deployment, usage, and administration.

##### Relationships and Interactions
- The Control Panel’s Frontend (Web UI) communicates with its backend PHP engine and API endpoints to display system status, manage configurations, and trigger server-side processes.
- The core engine, implemented in PHP and complemented with CLI scripts, orchestrates changes across the underlying server services. When an administrator triggers an action (for example, adding a domain or configuring a database), the control panel calls the corresponding command-line script (located in “bin”) and may update configuration files/templates.
- The installation/upgrade modules ensure that the control panel’s code and configuration are properly integrated with the underlying services on the target operating system (Debian/Ubuntu).
- External services (web server, DNS, mail, database, firewall) are managed through configuration files and service controllers/templates, with the control panel communicating with them (often via file modifications, service commands, or API calls).
- CI/CD pipelines and test suites are run during development and integration to ensure code quality.

##### Important Architectural Patterns and Design Principles
- Modularity: Each service (web, DNS, mail, database, firewall) has its own set of configuration and management scripts, allowing for isolated updates.
- Separation of Concerns: The clear division between the Web UI, backend business logic, command-line administrative tools, and installation/packaging components.
- Template-driven Deployment: Use of installation templates (for Apache, NGINX, mail, and DNS) to ensure consistency across deployments.
- Integration with Operating System Services: The project appears to embrace a “control and configure” approach rather than reimplementing server software; it leverages existing OS-level daemons and simply manages their configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        webUI["Web Interface (UI)"]:::presentation
        cli["CLI Tools"]:::presentation
    end

    subgraph "Application/Core Layer"
        phpApp["PHP Application Engine"]:::application
        api["API Endpoints"]:::application
    end

    subgraph "Integration Layer"
        webServers["Web Servers (Apache/NGINX)"]:::integration
        dns["DNS Service (Bind)"]:::integration
        mail["Mail Services (Dovecot/Exim,Roundcube)"]:::integration
        database["Database Servers (MariaDB/MySQL,PostgreSQL)"]:::integration
        firewall["Firewall & Security"]:::integration
        configTemplates["Configuration Templates"]:::integration
    end

    subgraph "Deployment & Configuration Layer"
        installer["Installer & Upgrade Scripts"]:::deployment
        packaging["Packaging Components"]:::deployment
    end

    subgraph "DevOps & CI/CD"
        cicd["CI/CD Pipelines & Automated Tests"]:::devops
        docs["Documentation & Guides"]:::devops
    end

    %% Connections between layers
    webUI -->|"requests"| phpApp
    phpApp -->|"triggers"| cli
    phpApp -->|"API_calls"| api

    %% CLI script actions on Integration Layer
    cli -->|"executes"| webServers
    cli -->|"executes"| dns
    cli -->|"executes"| mail
    cli -->|"executes"| database
    cli -->|"executes"| firewall

    %% API endpoints configuring Integration Layer
    api -->|"configures"| webServers
    api -->|"configures"| dns
    api -->|"configures"| mail
    api -->|"configures"| database
    api -->|"configures"| firewall
    api -->|"updates"| configTemplates

    %% Deployment flow updating Integration Layer
    installer -->|"installs_upgrades"| webServers
    installer -->|"installs_upgrades"| dns
    installer -->|"installs_upgrades"| mail
    installer -->|"installs_upgrades"| database
    installer -->|"installs_upgrades"| firewall
    packaging -->|"packages"| webServers
    packaging -->|"packages"| dns
    packaging -->|"packages"| mail
    packaging -->|"packages"| database
    packaging -->|"packages"| firewall

    %% DevOps feedback loop
    cicd -->|"tests"| phpApp
    cicd -->|"tests"| api
    docs ---|"references"| phpApp

    %% Click Events
    click webUI "https://github.com/sahsanu/hestiacp/tree/main/web/"
    click webUI "https://github.com/sahsanu/hestiacp/tree/main/web/src"
    click cli "https://github.com/sahsanu/hestiacp/tree/main/bin/"
    click phpApp "https://github.com/sahsanu/hestiacp/tree/main/web/src/app/"
    click api "https://github.com/sahsanu/hestiacp/tree/main/web/api/"
    click api "https://github.com/sahsanu/hestiacp/tree/main/install/common/api/"
    click installer "https://github.com/sahsanu/hestiacp/tree/main/install/"
    click installer "https://github.com/sahsanu/hestiacp/tree/main/install/upgrade/"
    click packaging "https://github.com/sahsanu/hestiacp/tree/main/src/deb/"
    click packaging "https://github.com/sahsanu/hestiacp/tree/main/install/deb/"
    click webServers "https://github.com/sahsanu/hestiacp/tree/main/install/deb/apache2/"
    click dns "https://github.com/sahsanu/hestiacp/tree/main/install/deb/bind/"
    click mail "https://github.com/sahsanu/hestiacp/tree/main/install/deb/exim/"
    click database "https://github.com/sahsanu/hestiacp/tree/main/install/deb/mysql/"
    click cicd "https://github.com/sahsanu/hestiacp/tree/main/.github/"
    click docs "https://github.com/sahsanu/hestiacp/tree/main/docs/"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#1f78b4,stroke-width:2px;
    classDef application fill:#90EE90,stroke:#33a02c,stroke-width:2px;
    classDef integration fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef deployment fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef devops fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
```
