Skip to content

An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.

2.0 KB
Raw Blame

Architecture Decision Records

This directory records architecture decisions for the Coolify v5 ecosystem: Coolify Laravel, Flux, coold, and the contracts between them.

ADRs are for decisions that are hard to reverse, surprising without context, and made after a real trade-off. If a note is just reference material, put it in the main architecture docs instead.

Index

ADR Decision
0001 Split v5 into Coolify control plane, Flux broker, and coold host agent.
0002 Keep coold as a narrow host agent with explicit primitives.
0003 Keep Flux as the connection broker between Coolify and coold.
0004 Keep Coolify Laravel as the product control plane.

Format

Use the next sequential number and a short slug:

0005-short-decision-slug.md

Start small. A useful ADR can be one paragraph:

# ADR 0005: Short title of the decision

Coolify v5 will ... because ... This trades ... for ...

Add optional sections only when they clarify the decision:

  • Status: Proposed, Accepted, Deprecated, or Superseded by ADR NNNN.
  • Context: what forced the decision.
  • Decision: what we chose.
  • Consequences: non-obvious benefits, costs, or follow-up constraints.
  • Considered options: rejected alternatives worth remembering.

Scope guide

  • Coolify ADRs cover product/control-plane state, RBAC, deployments, billing, APIs, UI-visible behavior, and durable audit/history.
  • Flux ADRs cover connection brokerage, host stream routing, request/response correlation, backpressure, and transport-level authentication.
  • coold ADRs cover host primitives, privileged execution, Podman/firewall/DNS, local safety rules, and agent lifecycle.
  • Cross-cutting ADRs belong here when the decision changes contracts between Coolify, Flux, and coold.