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:

text

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.