# donknap/dpanel architecture

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

- Interactive diagram: https://gitdiagram.com/donknap/dpanel
- Repository: https://github.com/donknap/dpanel

## Overview

##### Project type and purpose
- This is a full-stack Docker management panel (“DPanel”)
- Purpose: provide a web UI and CLI scripts to manage Docker containers, images, networks, volumes, backups, crons, SSL certificates, registry sync, etc.

##### Main architectural layers (based on file structure)
- Frontend: static assets in asset/index.html + asset/static (React, UmiJS, Ant Design)
- HTTP/API layer: Go controllers under app/application/http and common/http
- Application logic: app/application/logic and common/logic modules
- CLI commands: app/ctrl/command (compose, container, store, user), invoked by docker/script/*.yaml
- Service layer: common/service (docker SDK, crontab, ACME, storage, SSH, WebSocket, plugin, registry, notice)
- Data access layer: common/dao + common/accessor + common/entity (ORM-generated DAOs and option builders)
- Infrastructure/config: config.yaml, migrations under common/migrate, Dockerfiles, Makefile

##### External systems and dependencies
- Docker Engine via unix socket (/var/run/docker.sock)
- SQL database (models generated by gen-model.yaml)
- Nginx reverse proxy (docker/nginx)
- ACME service for certificates (common/service/acme)
- Optional remote storage via rclone (through plugin or storage service)
- Web browser (classic web UI)
- CLI scripts scheduled by host crontab or run manually

a. Frontend (Browser)
- Sends HTTP/HTTPS → Nginx
b. Nginx (Docker container)
- Serves static files
- Proxies API calls → Go HTTP server
c. Go HTTP Server (main.go)
- HTTP controllers → application logic → service layer → Docker Engine / DB / ACME / storage / plugin
- WebSocket endpoints → push events to front end
d. CLI Module (app/ctrl)
- Invoked by shell scripts under docker/script
- Shares the same service & data layers as the HTTP server
e. Service Layer
- Docker SDK calls to Docker Engine
- Cron job scheduling (wrapper around host crontab or internal scheduler)
- ACME for SSL
- Plugin loader & executor
- SSH and remote storage interactions
f. Data Layer
- ORM DAOs → SQL database
- Migrations manage schema versions
g. External Services
- Docker Engine
- Database (MySQL/PostgreSQL)
- Certificate Authority (Let’s Encrypt via ACME)
- Remote object storage (via rclone or other plugin)

##### Architectural patterns and design principles
- Layered architecture (Presentation → Application → Service → Data)
- MVC-like controllers for HTTP and CLI adapters
- Hexagonal/Ports & Adapters: services encapsulate external dependencies (Docker, DB, SSH, WebSocket)
- Reuse of core logic across HTTP and CLI interfaces

##### Essential details to capture
- Dual interfaces (HTTP + CLI) sharing the same core
- Docker Engine integration via unix socket
- Database persistence (common/dao) and migrations
- Plugin system and built-in scripts (docker/script)
- Certificate management (ACME)
- WebSocket events channel (common/service/ws)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Browser)"
        FUI["Static Assets\nasset/index.html, asset/static"]:::frontend
    end

    subgraph "Edge"
        NG["Nginx\ndocker/nginx/nginx.conf\nasset/nginx/vhost.tpl"]:::reverse
    end

    subgraph "Backend (Go)"
        A["Go HTTP Server\nmain.go"]:::backend

        subgraph "HTTP/API Layer"
            AC1["App Controllers\napp/application/http/controller"]:::backend
            AC2["Common Controllers\napp/common/http/controller"]:::backend
            AM1["App Middleware\napp/application/http/middleware"]:::backend
            AM2["Common Middleware\napp/common/http/middleware"]:::backend
        end

        subgraph "CLI Adapters"
            CLI1["Commands\napp/ctrl/command"]:::backend
            CLI2["SDK Types\napp/ctrl/sdk"]:::backend
        end

        subgraph "Logic"
            L1["App Logic\napp/application/logic"]:::backend
            L2["Common Logic\napp/common/logic"]:::backend
        end

        subgraph "Service Layer"
            S1["Docker SDK\ncommon/service/docker"]:::service
            S2["Compose Service\ncommon/service/compose"]:::service
            S3["Crontab Scheduler\ncommon/service/crontab"]:::service
            S4["ACME Certs\ncommon/service/acme"]:::service
            S5["Plugin System\ncommon/service/plugin"]:::service
            S6["SSH Client\ncommon/service/ssh"]:::service
            S7["Storage\ncommon/service/storage"]:::service
            S8["WebSocket Events\ncommon/service/ws"]:::service
            S9["Registry Sync\ncommon/service/registry"]:::service
            S10["Notification\ncommon/service/notice"]:::service
        end

        subgraph "Data Layer"
            DA["Data Accessor\ncommon/accessor"]:::service
            DAO["ORM DAOs\ncommon/dao"]:::service
            DE["Entities\ncommon/entity"]:::service
            MIG["Migrations\ncommon/migrate"]:::service
        end

        subgraph "Config & Infra"
            CFG["Config\nconfig.yaml"]:::service
            DF["Dockerfiles\nDockerfile, Dockerfile-lite"]:::service
            MK["Makefile\nMakefile"]:::service
            GEN["Model Gen\ndatabase/gen-model.yaml"]:::service
        end
    end

    subgraph "External Services"
        Dock["Docker Engine\n/var/run/docker.sock"]:::external
        DB["SQL Database"]:::external
        AC["Certificate Authority"]:::external
        RS["Remote Storage"]:::external
        Brow["Browser"]:::external
        Cron["Host Crontab"]:::external
    end

    Brow -->|HTTP/HTTPS| NG
    NG -->|serve static| FUI
    NG -->|proxy /api| A
    A -->|handles| AC1
    A -->|handles| AC2
    AC1 --> AM1
    AC2 --> AM2
    AM1 --> L1
    AM2 --> L2
    L1 --> S1
    L1 --> S2
    L1 --> S3
    L1 --> S4
    L1 --> S5
    L1 --> S6
    L1 --> S7
    L1 --> S8
    L1 --> S9
    L1 --> S10
    L2 --> S1
    Cron --> CLI1
    CLI1 --> L1
    CLI1 --> S1
    S1 --> Dock
    S2 --> Dock
    S3 --> Cron
    S4 --> AC
    S6 --> RS
    S1 --> DB
    S5 --> RS
    DAO --> DB
    MIG --> DB
    L1 --> DAO
    L2 --> DAO
    S8 --> Brow

    click FUI "https://github.com/donknap/dpanel/blob/master/asset/index.html"
    click FUI "https://github.com/donknap/dpanel/tree/master/asset/static/"
    click NG "https://github.com/donknap/dpanel/blob/master/docker/nginx/nginx.conf"
    click NG "https://github.com/donknap/dpanel/blob/master/asset/nginx/vhost.tpl"
    click A "https://github.com/donknap/dpanel/blob/master/main.go"
    click AC1 "https://github.com/donknap/dpanel/tree/master/app/application/http/controller/"
    click AC2 "https://github.com/donknap/dpanel/tree/master/app/common/http/controller/"
    click AM1 "https://github.com/donknap/dpanel/blob/master/app/application/http/middleware/home.go"
    click AM2 "https://github.com/donknap/dpanel/tree/master/app/common/http/middleware/"
    click L1 "https://github.com/donknap/dpanel/tree/master/app/application/logic/"
    click L2 "https://github.com/donknap/dpanel/tree/master/app/common/logic/"
    click CLI1 "https://github.com/donknap/dpanel/tree/master/app/ctrl/command/"
    click CLI2 "https://github.com/donknap/dpanel/tree/master/app/ctrl/sdk/"
    click S1 "https://github.com/donknap/dpanel/tree/master/common/service/docker/"
    click S2 "https://github.com/donknap/dpanel/tree/master/common/service/compose/"
    click S3 "https://github.com/donknap/dpanel/tree/master/common/service/crontab/"
    click S4 "https://github.com/donknap/dpanel/tree/master/common/service/acme/"
    click S5 "https://github.com/donknap/dpanel/tree/master/common/service/plugin/"
    click S6 "https://github.com/donknap/dpanel/tree/master/common/service/ssh/"
    click S7 "https://github.com/donknap/dpanel/tree/master/common/service/storage/"
    click S8 "https://github.com/donknap/dpanel/tree/master/common/service/ws/"
    click S9 "https://github.com/donknap/dpanel/tree/master/common/service/registry/"
    click S10 "https://github.com/donknap/dpanel/tree/master/common/service/notice/"
    click DA "https://github.com/donknap/dpanel/tree/master/common/accessor/"
    click DAO "https://github.com/donknap/dpanel/tree/master/common/dao/"
    click DE "https://github.com/donknap/dpanel/tree/master/common/entity/"
    click MIG "https://github.com/donknap/dpanel/tree/master/common/migrate/"
    click DF "https://github.com/donknap/dpanel/tree/master/Dockerfile"
    click DF "https://github.com/donknap/dpanel/tree/master/Dockerfile-lite"
    click CFG "https://github.com/donknap/dpanel/blob/master/config.yaml"
    click MK "https://github.com/donknap/dpanel/tree/master/Makefile"
    click GEN "https://github.com/donknap/dpanel/blob/master/database/gen-model.yaml"

    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef reverse fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef service fill:#F0F0F0,stroke:#A9A9A9,color:#555;
    classDef external fill:#E6E6FA,stroke:#9370DB,color:#9370DB;
```
