# productiveops/dokemon architecture

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

- Interactive diagram: https://gitdiagram.com/productiveops/dokemon
- Repository: https://github.com/productiveops/dokemon

## Overview

##### Main Components
- Backend Services:
- The Go-based server (located in cmd/server and pkg/server) handles API requests, manages Docker operations (using the pkg/dockerapi package), routes requests (see pkg/server/router), and stores data through modules in pkg/server/store.
- The Go-based agent (located in cmd/agent and pkg/agent) encapsulates functionality for executing Docker-related tasks and operations such as handling containers, images, networks, volumes, and more.
- Common utility and business logic libraries are distributed across pkg/common, pkg/crypto, and pkg/messages.
- Frontend:
- The web directory contains a full SPA (likely built with React/TypeScript and Vite) that provides the graphical user interface. This layer handles components (ui, widgets, side-nav, etc.), routing, and API communication with the backend server.
- Integration & Deployment:
- Docker-related artifacts (Dockerfile.agent, Dockerfile.server) and orchestration files (compose.yaml sample in the README and docker-compose instructions) indicate containerized deployment.
- A sample configuration for using Traefik with Let’s Encrypt shows the planned integration of the application behind a reverse proxy for secure, SSL-enabled access.
- External Services:
- Docker daemon itself serves as an external component that Dokémon interacts with, as seen from the mounting of /var/run/docker.sock.
- Optionally, an SSL-enabled reverse proxy (Traefik) externalizes secure access.

##### Relationships and Interactions
- The Web Frontend communicates with the Backend Server via REST API calls and websockets (note the pkg/server/handler/websocket.go) for real-time updates (container logs and status changes).
- The Backend Server orchestrates the management of Docker containers by interacting with the Docker API through the pkg/dockerapi package. It acts as the coordinator between the user’s actions on the web frontend and the agent’s execution of container tasks.
- The Agent component is designed to run on different target servers or as part of a distributed system, performing tasks delegated by the backend.
- The server modules (handlers, models, store) are built following a pattern that cleanly separates HTTP request handling, business logic processing, data validation, and persistent storage.
- Configuration and deployment follow best practices including container orchestration via Docker Compose and dynamic certificate management via Traefik.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different components (agent, server, web client) have clearly demarcated responsibilities.
- Modularization: Packages like pkg/agent, pkg/server, pkg/dockerapi, and pkg/crypto break down complex functionality into discrete, manageable modules.
- RESTful API & WebSockets: The use of dedicated API handlers and websocket support for real-time data streams.
- Containerization: Use of Dockerfiles, Docker Compose setups, and integration with external reverse proxies shows a commitment to portable, scalable deployment.
- Extensibility: The organized code structure (several handler and request/response modules) suggests the possibility of extending functionality without tightly coupling components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Web Frontend"
        WF["Web Frontend"]:::frontend
    end

    subgraph "Backend Server"
        APH["API Handlers"]:::backend
        WS["WebSocket Handler"]:::backend
        RT["Router"]:::backend
        ST["Data Storage (Store)"]:::backend
        DA["Docker API Integration"]:::docker
        CU["Common Utilities & Business Logic"]:::common
        REG["Registry"]:::backend
    end

    subgraph "Agent"
        AG["Agent"]:::agent
    end

    subgraph "Infrastructure"
        TRAF["Traefik Reverse Proxy"]:::infra
        DDA["Docker Daemon"]:::infra
        DEP["Deployment Artifacts"]:::infra
    end

    WF -->|"REST_API"| APH
    WF -->|"WebSocket"| WS
    APH -->|"routes"| RT
    APH -->|"stores-data"| ST
    APH -->|"business-logic"| CU
    APH -->|"docker-ops"| DA
    APH -->|"delegates-tasks"| AG
    CU -->|"image-repo"| REG
    DA -->|"executes-commands"| DDA
    TRAF -->|"secure-traffic"| APH
    DEP -->|"deploys-to"| DDA
    DEP -->|"deploys-proxy"| TRAF

    click WF "https://github.com/productiveops/dokemon/tree/main/web"
    click APH "https://github.com/productiveops/dokemon/tree/main/cmd/server"
    click WS "https://github.com/productiveops/dokemon/blob/main/pkg/server/handler/websocket.go"
    click RT "https://github.com/productiveops/dokemon/blob/main/pkg/server/router/router.go"
    click ST "https://github.com/productiveops/dokemon/tree/main/pkg/server/store"
    click DA "https://github.com/productiveops/dokemon/tree/main/pkg/dockerapi"
    click CU "https://github.com/productiveops/dokemon/tree/main/pkg/common"
    click REG "https://github.com/productiveops/dokemon/tree/main/pkg/registry"
    click AG "https://github.com/productiveops/dokemon/tree/main/cmd/agent"
    click DEP "https://github.com/productiveops/dokemon/blob/main/samples/wordpress/compose.yaml"

    classDef frontend fill:#F3E5AB,stroke:#333,stroke-width:2px;
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef agent fill:#C3FDB8,stroke:#333,stroke-width:2px;
    classDef docker fill:#D1E8E2,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFCCCB,stroke:#333,stroke-width:2px;
    classDef common fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
