Promote-to-scale: one image, demo to cluster

Most projects hide a second project inside them: the “now rewrite it for production” cliff. We design that cliff out from commit #1 with a single image that runs as a one-process demo and, by configuration, as a fleet of scaled services.

The promotion path

How it works

The application is built ports-and-adapters: a thin API layer, pure domain logic, and adapters for I/O. Every module exposes the same interface whether it’s called in-process or over the network. A packages.yaml declares which modules exist and how they bind; a small promote step reads it and renders either a Docker Compose file (everything in one container, for a demo or a small site) or a Helm chart (each load-bearing module as its own deployment, for scale).

Because it’s the same image either way, there’s no divergence: the binary that a stakeholder clicked through in week two is the binary that carries production load in month six.

How it was built

• Hexagonal from the start. Domain code never imports a framework or a driver; adapters do. Splitting a module out later is a wiring change, not a rewrite.
• Config, not forks. Environment drives everything — same image, different packages.yaml and env per environment. No if PROD branches in the code.
• Health contracts. Every module serves /healthz, /readyz, /metrics, /version, so the orchestrator can manage it identically at either scale.

The payoff is reversibility: you can start small, prove the thing, and scale only the parts that actually need it — without ever throwing work away.