V59, light ALA: twelve rules on plain Phoenix
Light ALA is the part of ALA that cost about what conventional Phoenix costs when seven variants of this store went through the same ten requirement changes. V59 is the variant that holds it. It starts from V0, the conventional app, and adds twelve rules. Nine come from the forms measured in that post, one from the hybrid that added composition roots, and two from what the hybrid’s run caught. It implements the base requirements, so you can read it as a starting point rather than as the end of a change run. The code is at ala_variants_elixir/v59-light-ala.
This is a reading of the checklist, not Spray’s ALA. Spray’s applications also compose by ports (§3.5, §7.2.3): a feature “creates instances of domain abstractions, configures the instances with feature specific details, and connects them together” (§2.2). V59 keeps the creating and configuring and replaces the connecting with calls.
What stays Phoenix
Everything a Phoenix team already writes stays as it is: contexts, LiveViews, handle_event, streams, PubSub, start_async, Mox, ExUnit. Pages branch, loop and pass values between calls. CheckoutLive.Index checks stock, calls the payment provider and completes the order in its own handlers, as V0’s does. There are no ports, no wire/3, no stories and no running trace. If you know V0, you can read V59 without a glossary.
The layers (rules 1–3)
Four layers, each depending only on the ones below:
| Layer | Peers may call each other | Modules |
|---|---|---|
| app | yes | LiveViews, ShopComponents, UndoRemoval, CartSession, Plugs.EnsureCart, Router, Calibration |
| contexts | no | Catalog, ShoppingCart, Orders, Payments |
| domain | no | GoodDeal.Domain.{Pricing, ShippingMethod, VolumeTier, PromoCode, StockStatus} |
| platform | yes | Repo, ProductEvents, Channel, Shop, the Ecto schemas, the payment provider |
Rule 1: no context calls another. In V0, Orders called ShoppingCart.Pricing to price the order it was writing. In V59 the page already holds the priced summary, so it passes it in: Orders.complete_checkout(shop, summary). This is what kept order history (S04) at V0’s cost in the change runs, where strict ALA paid 1.9× to carry the summary along wires.
Rule 2: calibration at the top. Every application literal lives in GoodDealWeb.Calibration, one %Channel{} per channel: shipping methods, promo codes, gift-wrap price, volume tiers, the low-stock threshold, the PO format. Lower layers read it from the struct they are handed, so StockStatus.of(channel, stock) reads channel.low_stock_threshold, and no context or rule holds a number from the requirements.
Rule 3: rules as named pure modules. A rule is a module named for its concept, configured by its caller, with no I/O: ShippingMethod.cost(method, subtotal), VolumeTier.discount(channel, subtotal), PromoCode.valid?(channel, code). One-line calls stay where they are; a rule earns its module by having a name and edge cases of its own.
Interfaces that don’t break (rules 5–9)
These came from measuring. Form 1, the first three rules alone, ran at V0’s cost but broke 1.44× as many existing tests per change, and every extra break was an interface: a context function growing an argument for each value passed down, an accessor renamed when a value split by channel, a rule’s return reshaped. Five rules fixed it:
- 5. Configuration passes once, as a struct. A page’s session values travel in one
%Shop{}, which carries the channel. A context function takes the shop first,ShoppingCart.apply_promo_code(shop, code), so a new input is a new field, not a new parameter. - 6. Rules are extended, not reshaped.
Pricing.summary/2may gain keys but keepssubtotal,discountandtotal. - 7. Tests sit at the page and the context. LiveView tests and context tests against Postgres pin behaviour. A rule keeps unit tests only for edges worth pinning directly:
VolumeTierTestchecks that the 5% tier starts at exactly 50,000. - 8. A value the domain needs is an enforced key.
%Channel{}enforces seven keys and defaults onlypromo_codes: %{}andvolume_tiers: [], where absence means “no offer”. A default that hides a missing value was how form 1b looked better than it was. - 9. A guard lives in the context function that writes the data, and refuses with a tagged error.
apply_promo_code/2returns{:error, :invalid_promo_code}whatever the page checked first. A name never changes meaning: a new meaning gets a new name.
A composition root per page (rule 10)
Each LiveView that uses configured parts has one private parts function, called from mount, that builds them. The cart and the portal edit a cart the same way, so their roots share one builder and pass their own channel, stream and repricing:
# CartLive.Index
defp parts(session),
do: CartSession.editor_parts(session, :storefront, :items, &assign_summary/1)
# CartSession
def editor_parts(session, channel, stream, reprice) do
shop = session_shop(session, channel)
%{
shop: shop,
pricing: &Calibration.pricing(shop.channel, &1),
undo: %UndoRemoval{shop: shop, stream: stream, reprice: reprice, window_ms: Calibration.undo_window_ms()}
}
end
mount assigns it once as parts, and handlers call parts.shop, parts.pricing.(cart) and parts.undo, where removing or restoring a line is one call that reprices through the page’s own function. No handler calls Calibration, CartSession or Application.fetch_env! itself. Nothing is wired: the parts are called and their results used, as anywhere in Phoenix.
| Page | Parts |
|---|---|
CartLive.Index | through editor_parts: shop (storefront), pricing, undo (stream :items) |
PortalLive.Index | through editor_parts: shop (portal), pricing, undo (stream :lines) |
CheckoutLive.Index | shop, pricing, success_url |
ProductLive.Index | shop |
ProductLive.Show | channel, for the stock badge |
How to read a page: start at its parts. It tells you which channel the page sells on, how it prices a cart, how removal is undone and which session cart it writes to. Then read the handler, then the context function it calls, then the rule that function hands a channel to.
The shared builder is a trade the linter forced. Each page first wrote its own root, and the two were alike enough for the clone check to flag them; sharing the builder fixed that, but a reader of the cart page now follows one call to CartSession to see what the page is made of. For two pages that edit a cart the same way, that is a concept with a name, editor_parts, so I kept it. A page that composes differently keeps its root inline, as checkout and the product pages do.
In the change run the roots cost 49 production lines over ten changes, and no later change went around them. They do not show everything: the promo form, shown prices and the live subscription sit outside them, which is how one missing check went unnoticed on the checkout page.
Two guards from the run (rules 11–12)
Rule 11: builders take keyword overrides, and tests build through them. A builder of a config or context struct takes the values it cannot do without as arguments and the rest as options, handed to struct!/2, which refuses a missing enforced key and an unknown one:
def shop(channel, overrides),
do: struct!(Shop, [channel: Calibration.channel(channel)] ++ overrides)
Tests never write a struct literal; they call shop(:storefront, cart_id: cart.id) and Calibration.channel(:portal, volume_tiers: []). In the run, a positional shop builder that gained one argument broke 119 tests at once through the shared fixture. Under rule 11 a new field is one more option.
Rule 12: a write to a session cart sees a current cart. In the run, a reorder written as a LiveView event used the shop its page built at mount. After the portal’s Submitted step, the LiveView session still named the completed draft, and the reordered lines went into it and were lost. In V59, each root’s mount attaches a guard:
|> CartSession.guard_open_cart(shop, ~p"/cart")
Before every event it asks ShoppingCart.cart_closed?/1. If the cart has closed, it drops the event, flashes “That cart is closed, so nothing changed. Please try again.” and reloads the page with a full request, so Plugs.EnsureCart puts an open cart in the session. Behind it, every ShoppingCart function that writes cart contents, and both Orders writers, refuse a closed cart with {:error, :cart_closed}, each with a context test. A write that gets past the page fails loudly instead of landing in a cart nobody reads again.
A LiveView can’t write the session, which is why the guard reloads rather than looking up a new cart in the event: a cart the session doesn’t name would be replaced on the next request, and the write lost the same way. Two narrow gaps remain, written up in DESIGN.md: the check and the write are not atomic, and a cart that closes during checkout’s payment gets the out-of-stock message.
Linter settings that keep it honest
The linter is how you notice when a change drifts from the design while you work. V59 runs ala_lint through a lint.exs beside the app, with the four layers above as the layer map:
cd ala_lint_elixir && mix run ../ala_variants_elixir/v59-light-ala/lint.exs
layers = [
{:app, [~r/GoodDealWeb\.CartLive\./, ~r/GoodDealWeb\.PortalLive\./, ~r/GoodDealWeb\.CheckoutLive\./,
~r/GoodDealWeb\.ProductLive\./, ~r/GoodDealWeb\.CartSession$/, ~r/GoodDealWeb\.UndoRemoval$/,
~r/GoodDealWeb\.ShopComponents$/, ~r/GoodDealWeb\.Calibration$/, ~r/GoodDealWeb\.Plugs\./,
~r/GoodDealWeb\.Router$/, ~r/GoodDealWeb$/], [peer_ok: true]},
{:contexts, [~r/^GoodDeal\.(Catalog|ShoppingCart|Orders|Payments)$/], [peer_ok: false]},
{:domain, [~r/GoodDeal\.Domain\./], [peer_ok: false]},
{:platform, [~r/GoodDeal\.Repo$/, ~r/GoodDeal\.ProductEvents$/, ~r/^GoodDeal\.(Channel|Shop)$/,
~r/^GoodDeal\.Catalog\.Product$/, ~r/^GoodDeal\.ShoppingCart\.(Address|Cart|CartItem|WishlistItem)$/,
~r/^GoodDeal\.Orders\.(LineItem|Order|PurchaseOrder)$/, ~r/GoodDealWeb\.CoreComponents$/], [peer_ok: true]}
]
# light ALA adopts layering, calibration at the top and named rules, not ports, wiring or
# composition-only pages, so the checks about those are off
checks = %{
r9: :off, r10: :off, r10_aggregate: :off, r11: :off, r11_share: :off,
ports: :off, ports_unwired: :off, ports_computed: :off,
wiring_closure: :off, hops: :off, vocabulary: :off, subcomponent: :off
}
AlaLint.analyze(lib, layers: layers, exclude: exclude, checks: checks, strict: true)
(The full file, with the excludes and all three tiers, is lint.exs.)
What each setting holds you to:
| Setting | Catches | Rule |
|---|---|---|
peer_ok: false on contexts | Orders calling ShoppingCart | 1 |
peer_ok: false on domain | one rule calling another instead of being configured with it | 1, 3 |
| the layer order | an upward edge: a context calling a page, a rule calling a context | 1 |
| R3, scored | a §7 number or a channel name in a context or rule | 2 |
R7 clone, scored under --strict | the same logic written twice, e.g. a handler copied into a second page | 3, 10 |
| R5, scored | a string two modules must agree on, such as a PubSub topic named like a table | 9 |
layer coverage (unassigned) | a new module no layer pattern matches, which every layer check would then skip | 1 |
| the twelve checks off | ports, wiring and composition-only pages, which light ALA does not adopt | — |
Three things to know when you read its output:
- Run it at
--strict. That is where the clone check scores, and the clone check is what notices a page handler copied rather than shared. In the change runs it was the most useful single check: it pushed shared undo and promo handling into one module each time a second page needed it. - A rule whose checks are all off reads as not adopted, not met, and is left out of the count (this was fixed on 2026-10-29; before it, R9 to R11 read as met). Under
--strict, V59 meets all seven of the checklist rules it adopts and checks (R1–R7; R8 is judgement). The last to fall was R7: the cart and portal remove/undo handlers were a 34-node clone until the repricing moved intoUndoRemoval. - Rules 11 and 12 have checks of their own; rules 8 and 9 do not.
builder_literals(rule 11) flags a%Channel{}or%Shop{}literal outside its builder, inlibortest/, and a builder that takes optional fields positionally.stale_session_write(rule 12) flags a LiveView whose events write the session cart while itsmountattaches no open-cart guard. V59 passes both; V56 is flagged for its literal channel fixture and four unguarded pages. Rules 8 and 9 (enforced keys, guards in the writer) are judgement; the context tests are their check: every writer that guards data has a test that it refuses.
Since 2026-10-29 the twelve :off entries are one switch: the linter’s light-ALA preset, a whitelist of the checks light ALA adopts. With ala_lint as a dependency, the layer map goes in a layers module (config :ala_lint, layers_module: MyAppWeb.AlaLayers, a module whose layers/0 returns the list above) and the rest in .ala_lint.exs:
%{
preset: :light_ala,
checks: %{
builder_literals: [structs: ["GoodDeal.Channel", "GoodDeal.Shop"], tests: ["test"]],
stale_session_write: [
writers: ["GoodDeal.ShoppingCart", "GoodDeal.Orders.complete_checkout",
"GoodDeal.Orders.submit_portal_order", "GoodDealWeb.UndoRemoval.finalize"],
except: [~r/^(get_|list_|cart_closed\?|check_stock)/],
guards: ["GoodDealWeb.CartSession.guard_open_cart"]
]
}
}
and mix ala.lint --strict reports R1 to R7 with R9 to R11 marked not adopted rather than met.
What it scores
- Tests: 175, 0 failures, three runs in a row (V58’s 151 plus 24 for the two guards: one per guarded writer, two for the order writers, and page tests for a cart closed in another tab). No behavioural assertion changed from V58; test edits are builder calls.
- Coverage: 99.61%, with V0’s ignores. The only uncovered lines are generated: the router’s unused
:apipipeline and oneFormComponentline. - Gates:
mix compile --warnings-as-errors,mix format --check-formattedandmix credo(353 modules and functions, no issues) are clean. - Lint: 100/A at normal, strict and super-strict through
lint.exs, with noala:acceptlines. The three remaining findings (app_share,module_avg,public_surface) are reported, never scored. R1–R7 met under--strict. - Size: 3,129 production lines (
lib/**/*.ex) and 2,353 test lines, against V58’s 3,054 and 2,062.
What it costs and what it buys
From the change runs: form 1c, V59’s first nine rules, used 1.07× V0’s tokens over ten changes, broke 19 of the previous step’s tests against V0’s 33, and scored 4.3 for design fit against V0’s 4.0. The composition roots added 49 production lines over the same ten changes. The two guards here have not been through the change sequence, so their cost over time is unmeasured; they and the clone fix add 75 production lines and 291 test lines to V58’s baseline, most of it the open-cart tests.
What it doesn’t buy: a drawing of the program, a running trace, or a part you can rewire into a second page without touching it. Those come with ports, which is where the change runs found ALA’s cost.