Incremental design

Incremental design grows the structure of a system one rung at a time. Each rung adds only what its slice needs and nothing it does not; a structural choice is left open until a slice forces it, recorded as an open decision until then. The opposite is up-front design: drawing the whole architecture before any slice exercises it — the big-bang the course argues against, because it bets correctness on a plan no rung has yet tested.

Two things make incremental design safe rather than chaotic. A stable seam — a facade the increments hang off — means adding structure above the seam never changes what is below it. And a deferred decision is recorded, not forgotten: the roadmap lists what is still open so the team knows which choices a later rung will force. The design is grown against real slices, behind a boundary that keeps the growth local.

The two strategies differ in when decisions are made. Designing all up front commits to every structural choice before the first slice ships — and some of those choices are made for slices that change, or never arrive, so a later rung would revise them. Growing incrementally commits only to the choices the first slice needs, and defers the rest until a slice forces each one. Switch the mode below to count the decisions made before the first slice ships, and how many of them a later rung would have changed.

F6 grows the Portal’s web design one rung at a time, behind one master invariant: “the web layer calls only the Portal facade and renders only %Portal.Error{}.” F6.1 adds only PortalWeb.Endpoint to the F5 supervision tree — the smallest structure that serves a page. The roadmap is explicit that later runtime pieces are deferred: “later rungs add Phoenix.PubSub and Phoenix.Presence only as the real-time features require them” (at F6.7). Authentication, the deploy target, and the dashboard are listed as open decisions, settled at F6.8–F6.9 when their slices force them.

The facade is the stable seam that makes this safe. Every rung adds web surface above it without reaching below, so the F5 engine, its event log, and its supervision tree never change underneath. The design grows; the foundation holds still.

# The master invariant — the seam the web design grows above:
#   the web layer calls only the Portal facade and renders only %Portal.Error{}

# Incremental: each rung adds only the structure its slice needs.
#   F6.1  + PortalWeb.Endpoint      (serve a page)
#   F6.7  + Phoenix.PubSub/Presence (only when real-time requires them)
#   F6.8  auth + deploy target      (open decisions, settled when forced)

id = Portal.ID.generate(:user)   # the slice calls the unchanged facade — nothing below it moves

Incremental design grows the structure of a system one rung at a time, adding only what the current slice needs and deferring the rest until a slice forces it. A stable seam — the facade — keeps each increment local, so the engine below never changes. On the Portal, F6 adds web surface rung by rung above the unchanged facade, with PubSub, auth, and the dashboard deferred to F6.7–F6.9. The next dive closes the module: feedback after every rung, the practice that makes small releases and incremental design pay.

Primary sources for incremental design and deferred decisions, and where this dive connects in the course and to the real F6 chapter.