# processmaker/pm4core-docker architecture

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

- Interactive diagram: https://gitdiagram.com/processmaker/pm4core-docker
- Repository: https://github.com/processmaker/pm4core-docker

## Overview

##### Project type and purpose
- This is a container-based full-stack demo environment for ProcessMaker 4 Core.
- It uses docker-compose to spin up all required services for local testing (web server, application, realtime broadcaster, cron jobs, database).

##### File structure
- Top-level Dockerfiles:
- Dockerfile.base defines the base image with system prerequisites.
- Dockerfile builds the application image on top of the base.
- docker-compose.yml orchestrates multiple services (app, web server, database, broadcaster, cron).
- build-files directory holds service-specific config and init scripts:
- init.sh: bootstraps install/seeding
- nginx.conf + services.conf: reverse-proxy rules
- laravel-cron: cron job container entrypoint
- laravel-echo-server.json: Socket.io config for realtime events

##### README for additional insights
- Describes environment variables (.env) that parameterize image tags, ports, host URL, and docker socket location.
- Explains bind-mounting the host Docker socket to allow script-executor containers to spawn new containers.
- Notes on building custom application and base images.

##### Main components
a. Docker Host & Engine
- The physical or VM host running Docker Engine / Docker Desktop
b. Containers (on a user-defined network)
1. nginx reverse-proxy container
2. pm4-core application container (PHP/Laravel + Node frontend)
3. database container (e.g. MySQL/Postgres)
4. laravel-cron container (runs scheduled tasks)
5. laravel-echo (Socket.io) broadcaster container
6. optional script-executor containers invoked via Docker socket bind-mount
c. External services
- Docker Hub (for pulling base and core images)
- Host file system (.env, config files, build-files)
- Developer’s browser (HTTP/Socket.io client)

##### Relationships and interactions
- Web requests from browser → nginx → pm4-core container
- pm4-core ↔ database over internal Docker network
- pm4-core emits events → laravel-echo-server (Socket.io) → browser clients
- laravel-cron container triggers scheduled jobs in pm4-core via artisan commands
- pm4-core can launch script-executor containers through the Docker socket volume
- docker-compose defines service dependencies, volumes, networks

##### Architectural patterns and design principles
- Isolation: each concern runs in its own container
- Reuse: Dockerfile.base and custom image tags promote a clear layering strategy
- Configuration-as-code: env vars and build-files externalize config
- Bind mount pattern for Docker socket to avoid Docker-in-Docker pitfalls

##### Detailed checklist
- Network overlay showing an isolated bridge network
– nginx
– pm4-core
– database
– laravel-cron
– laravel-echo-server
- Volumes and bind-mounts:
– /var/run/docker.sock → script-executor capability
– ./build-files & ./config → respective containers
- Ports mapping:
– host:8080 → nginx:80
– host:6001 → laravel-echo:6001
– Docker Hub → image pulls
– Browser ↔ nginx (HTTP & WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumers
    subgraph "External"
        Browser["Developer's Browser"]:::external
        DockerHub["Docker Hub"]:::external
    end

    %% Configuration & Orchestration
    Config[".env & docker-compose.yml"]:::config

    %% Docker Host & Engine
    subgraph "Docker Host"
        DockerEngine["Docker Engine / Docker Desktop"]:::host
        subgraph "Docker Bridge Network"
            Nginx["nginx Reverse-Proxy"]:::infra
            App["pm4-core Application"]:::core
            DB["Database (MySQL/Postgres)"]:::infra
            Cron["Laravel Cron"]:::aux
            Echo["Laravel Echo (Socket.io)"]:::aux
            Exec["Script-Executor Capability"]:::aux
        end
    end

    Init["Init & Seeding Scripts"]:::config

    %% External interactions
    Browser -->|HTTP/WS Requests| Nginx
    DockerHub -->|Image Pulls| DockerEngine
    Config -->|Env Vars| DockerEngine

    %% Internal flows
    Nginx -->|Reverse Proxy| App
    App -->|SQL Queries| DB
    App -->|Emit Events| Echo
    Echo -->|WebSocket| Browser
    Cron -->|Scheduled Jobs| App
    App -->|Launch Containers| Exec
    Init -->|Bootstrap & Seed| DB
    Init -->|Bootstrap & Seed| App

    %% Port mappings annotation
    Nginx -.->|Host:8080→80| Browser
    Echo -.->|Host:6001→6001| Browser

    %% Click Events
    click Nginx "https://github.com/processmaker/pm4core-docker/blob/master/build-files/nginx.conf"
    click Nginx "https://github.com/processmaker/pm4core-docker/blob/master/build-files/services.conf"
    click Nginx "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click App "https://github.com/processmaker/pm4core-docker/blob/master/Dockerfile.base"
    click App "https://github.com/processmaker/pm4core-docker/tree/master/Dockerfile"
    click App "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click DB "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click Cron "https://github.com/processmaker/pm4core-docker/tree/master/build-files/laravel-cron"
    click Cron "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click Echo "https://github.com/processmaker/pm4core-docker/blob/master/build-files/laravel-echo-server.json"
    click Echo "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click Exec "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click Config "https://github.com/processmaker/pm4core-docker/blob/master/.env"
    click Config "https://github.com/processmaker/pm4core-docker/blob/master/docker-compose.yml"
    click Init "https://github.com/processmaker/pm4core-docker/blob/master/build-files/init.sh"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef host fill:#eef,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef infra fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef aux fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef config fill:#ddd,stroke:#333,stroke-width:1px
```
