# mydnshost/mydnshost-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/mydnshost/mydnshost-frontend
- Repository: https://github.com/mydnshost/mydnshost-frontend

## Overview

##### Project type and purpose
- This is a full-stack “frontend” web application written in PHP.
- It provides a browser-based UI for managing DNS entries by calling a separate JSON API (the mydnshost-api repo).
- It uses Composer for dependency management, Docker for containerization, and GitHub Actions for CI.

##### File structure
- Top-level:
- `.github/` (CI workflows)
- `Dockerfile` (container build)
- `composer.json`/`composer.lock` (PHP deps)
- `public/` (web-server docroot, contains `index.php` + `.htaccess`)
- `src/` (PHP application code)
- `templates/` (presentation layer – `.tpl` template files + assets)
- In `src/`:
- `DisplayEngine.php` (templating/rendering engine)
- `routes/` (one class per route group: Admin, User, Domain, Authenticated vs. Not, System Jobs/Services, Terms, etc.)
- `session.php` (session management)
- `storage.php` (client library wrapper for the JSON API – via the mydnshost-php-api submodule)
- In `templates/`:
- A default theme folder with SCSS/JS assets (front-end behavior & styling) and numerous `.tpl` files for each view.

##### README for additional insights
- Confirms that this is the “main frontend” and interacts with an external JSON API.
- Notes that production is typically deployed as a Docker container.
- No internal database – all persistence happens in the API service.

a. Client Web Browser (UI)
- Loads HTML/CSS/JS assets delivered by the PHP server.
b. Frontend Web Server (Docker container)
- Nginx or Apache + PHP-FPM (public/index.php)
- Routes via src/routes/* classes
- DisplayEngine renders templates from templates/default
- session.php + storage.php manage user sessions and API client calls
c. External JSON API Service
- mydnshost-api (calls over HTTPS)
- Handles all data persistence (DB, authentication, email)
d. CI/CD Pipeline
- GitHub Actions workflow (.github/workflows/automerge.yml)
- Builds Docker image, runs tests, auto-merges dependency bumps via dependabot
e. Optional: Docker Registry / Deployment
- Registry holding built images
- Infrastructure repo (mydnshost-infra) for deployment manifests

##### Relationships & interactions
- Browser → (HTTP/HTTPS) → Frontend Web Server
- Frontend Web Server → (JSON over HTTPS) → External JSON API
- CI/CD → (build & push) → Docker Registry → Deployment targets
- Git Repository → CI/CD triggers on push/pull_request

##### Architectural patterns & design principles
- MVC-style separation:
- Controllers: route classes in src/routes
- Model/Service: storage.php + mydnshost-php-api client
- View: templates/default/*.tpl
- Single responsibility per route class
- Configuration in config.php
- Dependency management with Composer
- Containerized, stateless service (sessions can be file or redis, per config)

##### Detail without over-splitting
- Enough to capture the MVC layers, external API boundary, and deployment flow.

- The separation between frontend UI, application server, and data API layers
- The internal MVC-style structure
- The deployment and CI/CD landscape
- The key technologies: PHP & Composer, Docker, GitHub Actions, external JSON API

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Layer
    subgraph "User Layer" 
        style UserBrowser fill:#E0F7FA,stroke:#006064
        UserBrowser["Client Web Browser"]
    end

    %% Application Layer
    subgraph "Application Layer (PHP Frontend - Docker Container)"
        style AppLayer fill:#E8F5E9,stroke:#256029
        DockerContainer["Docker Container\n(PHP + Nginx/Apache)"]
        Composer["Composer Dependencies"]
        Config["Configuration\n(config.php)"]
        subgraph "MVC Components"
            style MVC fill:#FFFFFF,stroke:#256029,stroke-dasharray: 5 5
            Index["public/index.php"]
            Router["Routing Controllers\n(src/routes/)"]
            DisplayEngine["DisplayEngine\n(src/DisplayEngine.php)"]
            Session["Session Management\n(src/session.php)"]
            Storage["API Client Service\n(src/storage.php)"]
            Templates["View Templates\n(templates/default/)"]
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        style DataLayer fill:#FFF3E0,stroke:#E65100
        APIService["External JSON API Service\n(mydnshost-api)"]
        Database["Database (managed by API)"]
    end

    %% CI/CD Pipeline
    subgraph "CI/CD & Deployment"
        style CICD fill:#ECEFF1,stroke:#455A64
        CI["GitHub Actions\n(.github/workflows/automerge.yml)"]
        Dependabot["Dependabot\n(.github/dependabot.yml)"]
        DockerRegistry["Docker Registry"]
        InfraRepo["Infrastructure Manifests\n(my­n­dns­host-infra)"]
    end

    %% Connections
    UserBrowser -->|"HTTP/HTTPS"| DockerContainer
    DockerContainer -->|serves| Index
    Index -->|routes to| Router
    Router -->|invokes| DisplayEngine
    DisplayEngine -->|renders| Templates
    Router -->|uses| Session
    Router -->|calls| Storage
    Storage -->|"JSON over HTTPS"| APIService
    APIService -->|persists| Database

    CI -->|builds & pushes| DockerRegistry
    CI -->|triggers on push| CI
    Dependabot -->|updates deps| CI
    DockerRegistry -->|deploys| InfraRepo

    %% Inside Container dependencies
    DockerContainer --> Composer
    DockerContainer --> Config
    DockerContainer --> MVC

    %% Click Events
    click Index "https://github.com/mydnshost/mydnshost-frontend/blob/master/public/index.php"
    click Router "https://github.com/mydnshost/mydnshost-frontend/tree/master/src/routes/"
    click DisplayEngine "https://github.com/mydnshost/mydnshost-frontend/blob/master/src/DisplayEngine.php"
    click Session "https://github.com/mydnshost/mydnshost-frontend/blob/master/src/session.php"
    click Storage "https://github.com/mydnshost/mydnshost-frontend/blob/master/src/storage.php"
    click Templates "https://github.com/mydnshost/mydnshost-frontend/tree/master/templates/default/"
    click Composer "https://github.com/mydnshost/mydnshost-frontend/blob/master/composer.json"
    click Composer "https://github.com/mydnshost/mydnshost-frontend/blob/master/composer.lock"
    click Config "https://github.com/mydnshost/mydnshost-frontend/blob/master/config.php"
    click DockerContainer "https://github.com/mydnshost/mydnshost-frontend/tree/master/Dockerfile"
    click CI "https://github.com/mydnshost/mydnshost-frontend/blob/master/.github/workflows/automerge.yml"
    click Dependabot "https://github.com/mydnshost/mydnshost-frontend/blob/master/.github/dependabot.yml"

    %% Styles
    classDef userLayer fill:#E0F7FA,stroke:#006064
    classDef appLayer fill:#E8F5E9,stroke:#256029
    classDef dataLayer fill:#FFF3E0,stroke:#E65100
    classDef cicd fill:#ECEFF1,stroke:#455A64
    class UserBrowser userLayer
    class DockerContainer,Composer,Config appLayer
    class APIService,Database dataLayer
    class CI,Dependabot,DockerRegistry,InfraRepo cicd
```
