# abdullahalharun/coolify architecture

> Architecture diagram of the GitHub repository abdullahalharun/coolify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullahalharun/coolify
- Repository: https://github.com/abdullahalharun/coolify

## Overview

1. **What this system is**
   - Coolify is a self-hosted control plane for deploying and operating applications, databases, services, and proxies on remote machines.
   - The repository is primarily a **Laravel** application with **Livewire** UI, but it also ships companion Docker images and deployment templates that are part of the platform architecture.

2. **Core control-plane shape**
   - The main app stores platform state in its own database: users, teams, servers, projects, environments, applications, databases, services, tags, secrets, backups, subscriptions, and webhooks.
   - It does not host customer workloads directly; instead, it orchestrates them on managed servers over SSH/Docker.

3. **Primary user-facing layer**
   - The UI is mostly **Livewire + Blade** components under `app/Livewire` and `resources/views/livewire`.
   - Routes are split into web UI, API, console, and webhook endpoints.
   - The UI covers onboarding, server management, project/resource configuration, deployments, databases, backups, logs, terminal access, settings, and subscription/admin screens.

4. **API boundary**
   - The API controllers under `app/Http/Controllers/Api` expose resource management for applications, databases, servers, projects, services, teams, security, and deployment operations.
   - `openapi.json` / `openapi.yaml` and the `Generate/OpenApi` command indicate the API is documented and treated as a first-class interface.

5. **Domain model and tenancy**
   - The architecture is organized around `Team -> Project -> Environment -> Resource` relationships.
   - Resources include:
     - applications
     - services
     - standalone databases
     - storage volumes
     - scheduled tasks
     - tags
   - Access control is enforced through policies and middleware, with API-specific checks for abilities, allowed IPs, and sensitive data masking.

6. **Orchestration and execution layer**
   - The heart of the system is in `app/Actions` and `app/Jobs`.
   - Actions encapsulate operations like generate config, start/stop/restart apps and databases, proxy control, server validation, cleanup, and remote command execution.
   - Jobs handle asynchronous workflows such as deployments, backups, server checks, Docker cleanup, SSL renewal, pull/push update tasks, notification dispatch, and subscription/billing processing.

7. **Remote server boundary**
   - Coolify talks to managed servers using SSH and Docker-centric commands, with helpers for multiplexing and SSL.
   - Remote actions include installing Docker, running commands, pulling logs/files, checking container status, managing proxies, and starting platform agents/sentinels.
   - The key architectural boundary is: **central Laravel control plane** versus **remote infrastructure nodes** where workloads actually run.

8. **Runtime coordination**
   - Background processing uses Laravel queue infrastructure with **Horizon** and scheduler commands.
   - Console commands support queue cleanup, server/resource checks, update flows, environment seeding, and maintenance tasks.
   - This means many visible UI actions are really requests that enqueue work and then reflect state changes later via jobs/events.

9. **Realtime and terminal subsystems**
   - The repo contains a dedicated `docker/coolify-realtime` service, including a terminal server and Soketi entrypoint.
   - Realtime is used for live status updates, logs, and terminal-like interactions rather than being part of the main web request lifecycle.
   - This is a separate operational component from the Laravel app and should be shown as an adjacent service in an architecture diagram.

10. **Eventing and notifications**
   - The app raises events for status changes, backups, tunnel changes, cleanup completion, SSL, server reachability, and service checks.
   - Listeners and notification classes fan these events out to email, Discord, Slack, Telegram, and Pushover.
   - There is also a transactional email path for auth, invitations, resets, and operational messages.

11. **Integrations with external systems**
   - Source control providers: GitHub, GitLab, Bitbucket, Gitea webhooks and OAuth/app integrations.
   - Billing: Stripe subscription and invoice handling.
   - Cloud/network helpers: Cloudflare tunnels and related server configuration flows.
   - Identity and auth extensions appear through Fortify, Sanctum, Socialite, and OAuth settings.

12. **Persistence and schema**
   - The system relies heavily on a relational database with a large migration history, indicating the schema is the source of truth for platform configuration.
   - Models mirror infrastructure entities and operational artifacts such as deployment queues, executions, backups, certificates, cleanup runs, and notifications.
   - Secrets and keys are handled as first-class persisted resources, with encryption-related migrations and helper traits.

13. **Deployment packaging**
   - The repository includes Dockerfiles and compose files for development, production, Windows, helper, realtime, and testing-host modes.
   - There are also scripts for install, upgrade, cloud upgrade, sync, and nightly distribution.
   - This means the repo is both the application source and the packaging/source-of-truth for how Coolify itself is deployed.

14. **Template-driven app bootstrapping**
   - `templates/compose` contains a large catalog of ready-made Docker Compose templates for popular apps and databases.
   - These templates are used to accelerate resource creation and encode supported deployment patterns.
   - In diagram terms, they are an input catalog feeding the project/resource creation flows, not runtime services themselves.

Main entry points: [`app/Actions`](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Actions) (Actions), [`routes/web.php`](https://github.com/abdullahalharun/coolify/blob/v4.x/routes/web.php) (Web UI), [`app/Jobs`](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Jobs) (Jobs), [`app/Models/Server.php`](https://github.com/abdullahalharun/coolify/blob/v4.x/app/Models/Server.php) (Servers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_control_plane["Control Plane"]
  node_node_routes_ui["Web UI<br/>routes/livewire<br/>[web.php]"]
  node_node_routes_api["API Surface<br/>routes/controllers<br/>[api.php]"]
  node_node_domain_models[("Domain Models<br/>Eloquent models")]
  node_node_policies_mw["Access Control<br/>policies/middleware"]
end

subgraph group_group_runtime["Execution"]
  node_node_actions["Actions"]
  node_node_jobs["Jobs<br/>async workflows"]
  node_node_commands["Console<br/>artisan commands"]
  node_node_services["Services"]
  node_node_events(("Events"))
  node_node_notifications["Notifications<br/>delivery channels"]
end

subgraph group_group_remote["Remote Infra"]
  node_node_remote_servers[("Servers<br/>managed nodes<br/>[Server.php]")]
  node_node_remote_docker["Docker Ops<br/>remote docker control"]
  node_node_realtime{{"Realtime Service<br/>socket/terminal service"}}
end

subgraph group_group_packaging["Packaging"]
  node_node_templates["Compose Templates<br/>deployment catalog"]
  node_node_docker_images["Coolify Images<br/>container packaging"]
  node_node_scripts["Install Scripts<br/>ops scripts"]
end

subgraph group_group_integrations["Integrations"]
  node_node_external_scm(("Git Providers<br/>source control"))
  node_node_external_billing(("Stripe Billing<br/>billing integration<br/>[Stripe.php]"))
  node_node_external_cloud(("Cloudflare<br/>network integration"))
end

node_node_routes_ui -->|"reads/writes"| node_node_domain_models
node_node_routes_ui -->|"triggers"| node_node_actions
node_node_routes_api -->|"CRUD"| node_node_domain_models
node_node_routes_api -->|"guards"| node_node_policies_mw
node_node_actions -->|"uses"| node_node_services
node_node_actions -->|"operates on"| node_node_remote_servers
node_node_actions -->|"executes"| node_node_remote_docker
node_node_jobs -->|"dispatches"| node_node_actions
node_node_jobs -->|"emits"| node_node_events
node_node_events -->|"fan-out"| node_node_notifications
node_node_commands -->|"schedules"| node_node_jobs
node_node_commands -->|"checks/maintains"| node_node_remote_servers
node_node_realtime -->|"streams to"| node_node_routes_ui
node_node_realtime -->|"bridges"| node_node_remote_servers
node_node_templates -->|"bootstraps"| node_node_routes_ui
node_node_docker_images -->|"packages"| node_node_actions
node_node_scripts -->|"deploys"| node_node_docker_images
node_node_external_scm -->|"webhooks"| node_node_routes_api
node_node_external_billing -->|"billing events"| node_node_jobs
node_node_external_cloud -->|"configures"| node_node_remote_servers

click node_node_routes_ui "https://github.com/abdullahalharun/coolify/blob/v4.x/routes/web.php"
click node_node_routes_api "https://github.com/abdullahalharun/coolify/blob/v4.x/routes/api.php"
click node_node_domain_models "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Models"
click node_node_policies_mw "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Policies"
click node_node_actions "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Actions"
click node_node_jobs "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Jobs"
click node_node_commands "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Console/Commands"
click node_node_services "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Services"
click node_node_events "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Events"
click node_node_notifications "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Notifications"
click node_node_remote_servers "https://github.com/abdullahalharun/coolify/blob/v4.x/app/Models/Server.php"
click node_node_remote_docker "https://github.com/abdullahalharun/coolify/tree/v4.x/app/Actions/Docker"
click node_node_realtime "https://github.com/abdullahalharun/coolify/tree/v4.x/docker/coolify-realtime"
click node_node_templates "https://github.com/abdullahalharun/coolify/tree/v4.x/templates/compose"
click node_node_docker_images "https://github.com/abdullahalharun/coolify/tree/v4.x/docker"
click node_node_scripts "https://github.com/abdullahalharun/coolify/tree/v4.x/scripts"
click node_node_external_billing "https://github.com/abdullahalharun/coolify/blob/v4.x/app/Http/Controllers/Webhook/Stripe.php"
click node_node_external_cloud "https://github.com/abdullahalharun/coolify/blob/v4.x/app/Actions/Server/ConfigureCloudflared.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_routes_ui,node_node_routes_api,node_node_domain_models,node_node_policies_mw toneBlue
class node_node_actions,node_node_jobs,node_node_commands,node_node_services,node_node_events,node_node_notifications toneAmber
class node_node_remote_servers,node_node_remote_docker,node_node_realtime toneMint
class node_node_templates,node_node_docker_images,node_node_scripts toneRose
class node_node_external_scm,node_node_external_billing,node_node_external_cloud toneIndigo
```

## Components

### Control Plane

Laravel core that stores state, exposes UI/API, and coordinates operations.

- [Web UI](https://github.com/abdullahalharun/coolify/blob/v4.x/routes/web.php): routes/livewire · User-facing routes and Livewire/Blade screens for onboarding, projects, servers, settings, and terminal. · `routes/web.php`
- [API Surface](https://github.com/abdullahalharun/coolify/blob/v4.x/routes/api.php): routes/controllers · Resource-management API endpoints plus OpenAPI documentation. · `routes/api.php`
- [Domain Models](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Models): Eloquent models · Persistent platform entities such as teams, projects, environments, resources, secrets, backups, and subscriptions. · `app/Models`
- [Access Control](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Policies): policies/middleware · Authorization, allowed-IP checks, sensitive-data masking, and auth/session boundaries. · `app/Policies`

### Execution

Asynchronous jobs, actions, and console processes that do the work.

- [Actions](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Actions): orchestration actions · Synchronous orchestration primitives for config generation, server validation, proxy control, and remote command execution. · `app/Actions`
- [Jobs](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Jobs): async workflows · Queued deployments, backups, cleanup, updates, checks, notifications, and billing processing. · `app/Jobs`
- [Console](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Console/Commands): artisan commands · Scheduler, Horizon, maintenance, cleanup, seeding, generation, and update commands. · `app/Console/Commands`
- [Services](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Services): core services · Configuration generation, repositories, Docker parsing, and proxy dashboard cache. · `app/Services`
- [Events](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Events): domain events · Status, backup, proxy, tunnel, cleanup, SSL, and server reachability events. · `app/Events`
- [Notifications](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Notifications): delivery channels · Email and third-party notifications for application, server, database, and task outcomes. · `app/Notifications`

### Remote Infra

Managed servers, Docker, SSH, proxy, and realtime adjunct services.

- [Servers](https://github.com/abdullahalharun/coolify/blob/v4.x/app/Models/Server.php): managed nodes · Remote machines that host Docker workloads and platform agents, reached over SSH. · `app/Models/Server.php`
- [Docker Ops](https://github.com/abdullahalharun/coolify/tree/v4.x/app/Actions/Docker): remote docker control · Container status, start/stop/restart, cleanup, logs, and proxy/database lifecycle on remote hosts. · `app/Actions/Docker`
- [Realtime Service](https://github.com/abdullahalharun/coolify/tree/v4.x/docker/coolify-realtime): socket/terminal service · Separate realtime service for live updates, Soketi, and terminal traffic. · `docker/coolify-realtime`

### Packaging

Docker images, scripts, and deployment/runtime packaging for Coolify itself.

- [Compose Templates](https://github.com/abdullahalharun/coolify/tree/v4.x/templates/compose): deployment catalog · Template library used to bootstrap applications and databases from compose patterns. · `templates/compose`
- [Coolify Images](https://github.com/abdullahalharun/coolify/tree/v4.x/docker): container packaging · Dockerfiles and compose definitions for development, production, helper, testing-host, and realtime images. · `docker`
- [Install Scripts](https://github.com/abdullahalharun/coolify/tree/v4.x/scripts): ops scripts · Install, upgrade, cloud-upgrade, sync, and nightly distribution scripts. · `scripts`

### Integrations

External systems and inbound/outbound integration boundaries.

- **Git Providers**: source control · GitHub, GitLab, Bitbucket, and Gitea integrations via webhooks and OAuth/app settings.
- [Stripe Billing](https://github.com/abdullahalharun/coolify/blob/v4.x/app/Http/Controllers/Webhook/Stripe.php): billing integration · Subscriptions, invoices, trials, and payment webhooks. · `app/Http/Controllers/Webhook/Stripe.php`
- [Cloudflare](https://github.com/abdullahalharun/coolify/blob/v4.x/app/Actions/Server/ConfigureCloudflared.php): network integration · Cloudflare tunnel and related server configuration flows. · `app/Actions/Server/ConfigureCloudflared.php`

## Connections

- Web UI → Domain Models: reads/writes · UI screens manage platform state and resource configuration.
- Web UI → Actions: triggers · User actions enqueue orchestration and remote operations.
- API Surface → Domain Models: CRUD · API controllers expose resource and team management.
- API Surface → Access Control: guards · API requests enforce abilities, allowed IPs, and sensitive data masking.
- Actions → Services: uses · Actions rely on generators, repositories, and parsing services.
- Actions → Servers: operates on · Actions coordinate work on managed servers.
- Actions → Docker Ops: executes · Remote lifecycle work is carried out through Docker-centric commands.
- Jobs → Actions: dispatches · Queued workflows reuse orchestration actions.
- Jobs → Events: emits · Jobs publish lifecycle and outcome events.
- Events → Notifications: fan-out · Listeners convert events into user-facing messages.
- Console → Jobs: schedules · Console commands manage queue, scheduler, maintenance, and update workflows.
- Console → Servers: checks/maintains · Commands perform server checks, cleanup, seeding, and update flows.
- Realtime Service → Web UI: streams to · Realtime updates power live logs, status, and terminal interactions.
- Realtime Service → Servers: bridges · Realtime terminal and status traffic bridges the control plane and nodes.
- Compose Templates → Web UI: bootstraps · Compose templates feed project and resource creation flows.
- Coolify Images → Actions: packages · Docker images define how the control plane and worker roles run.
- Install Scripts → Coolify Images: deploys · Scripts install and upgrade packaged runtime images.
- Git Providers → API Surface: webhooks · Source-control events enter through webhook and OAuth integrations.
- Stripe Billing → Jobs: billing events · Stripe events are processed asynchronously.
- Cloudflare → Servers: configures · Cloudflare tunnel integration configures remote infrastructure.