Get Down with ALA, a Zero-Coupled Architecture

Applying John Spray's Abstraction Layered Architecture to Elixir and Ruby web apps.

This is a single-topic site. It explores code architecture ideas from John Spray's Abstraction Layered Architecture (ALA), an online book (with C# code examples in his GitHub), applying ALA to other programming languages and applications, initially Elixir and its Phoenix LiveView web framework and Ruby on Rails.

Spray's argument, briefly: software degrades into a big ball of mud because of coupling, where modules come to depend on their peers and on things more specific than themselves, and no amount of layering-by-containment removes it. ALA's target is specifically design-time coupling, the dependencies written into the source, where one module's code names and relies on another. It drives those to zero between peers, permitting a dependency only downward, from a concrete piece to a more abstract, more stable one, so in that sense the code is strictly zero-coupled. What it does not forbid is run-time coupling: while the program runs, abstractions still exchange data and events, but only through wires connected in a higher layer, so two peers interact without either one's source knowing the other exists. Zero-coupled at design time, fully connected at run time. Spray claims this buys what object-oriented, layered, hexagonal, and clean-architecture approaches aim at but reach less completely: abstractions that are reusable, replaceable, and testable in isolation; code you can understand a piece at a time; changes that stay local; and a top layer that reads like the requirements. Those claims are his. Testing how far they hold in popular web app frameworks is the point of this site.

Application instantiate, configure, wire. All the product's knowledge, none of its logic (R3, R11) rates = { standard: 599, free_above: 5000 } words = { empty: "Your cart is empty." } low_at = 5 configuration goes in once (R3, R9) Lines.new(store:) Totals.new(rates:) Summary.new(words:) its state in its own store keeps only the last values it was sent renders what it is given contents summary wires: an output announces a fact, the layer above decides where it goes; a port's type is a paradigm, never a peer (R9) a wire meets another only here (R2); the composition reads as the requirements, and a test finds every port left open (R8) when this outgrows one abstraction, a Features layer of smaller compositions with ports goes under it (§2.2) new Domain abstractions one concept each, with configuration, ports and its own state (R4, R6, R7) Lines Totals Summary no association, no inheritance, no shared entity, no name agreed between two of them (R1, R5, R10): a class knows nothing of its peers Programming paradigms what a wire means and how it runs: the port types, and the execution models DataFlow (push) Event RequestResponse (pull) UiLayout StateMachine Foundation the wiring operator, value types, persistence: what every layer may depend on Ports: wire_to, on Money tables, one per feature a gateway, a stream, a job design-time dependencies only drop, onto something significantly more abstract (R1) run-time data and events move sideways, only along a wire the layer above connected
The whole of ALA in one picture. Classes in the lower layers know nothing of each other; the application creates their instances, gives each its configuration, and connects them port to port. Every dependency written in the source points down; everything that moves at run time moves along a wire. The R-numbers are the checklist rules that check each part.

My motivation is to dabble with ALA myself and to express it in a compact form for functional and object-oriented programming and provide tooling and templates, to help others to try and evaluate it as a distinct architectural choice. I'm not saying it's a good or the best way, just a way that intrigues me, and is compatible with some other software principles I find useful or appealing.

So far: an ALA Checklist of eleven rules, in a general edition and an Elixir one; eighteen designs of the same Phoenix LiveView storefront, each scored against it by hand; and a linter that scores the rules a machine can check. Six designs score 100 on the full walk. One does it in plain LiveView that a Phoenix developer reads at a glance, and another adds Spray's Features layer and meets every rule the linter checks at its strictest. Most of the top designs draw their wiring diagrams from the code itself, and a field guide says which technique solves which rule. Then the same storefront in Ruby on Rails: object-oriented and Ruby editions of the checklist, a Ruby linter that reads the syntax tree directly, and a Rails design in plain Ruby that meets every rule the linter checks at its strictest, with a reckoning of what Rails and Ruby force and what they don't.

Exploring ALA yourself? With a web app, a design, a tool, an analysis, or just thoughts? Add it to Awesome ALA, a community list where anyone can share links to their own explorations.

Introduction to ALA

ALA in Phoenix LiveView

  • The thermometer grows up: Spray's next three steps, in Elixir

    The first thermometer stops where Spray's book starts climbing. Here are his next steps (build then run, instances with ports, several kinds of wiring) and some Elixir ways to take each one, ending in a LiveView.

  • The coffee maker: an ALA model that nests cleanly inside LiveView

    Robert Martin's Mark IV coffee maker, reworked in Abstraction Layered Architecture and dropped into a Phoenix LiveView, where the pure model needed no changes to fit the framework. ALA Checklist Score: 97 (Lint, 8 of 10 rules met) 95 (Full). Familiarity (4/5)

  • How close can a LiveView app come to ideal ALA?

    Spray's application layer has no if statements and no data handling. A LiveView page is handed events, URLs, and a lifecycle. Which departures does the framework actually force, which only look forced, and how far did the variants get? Six score 100 on the full hand walk with Spray's statements read strictly, and V50, plain LiveView at familiarity 5, is the one to adopt by default. Here is how they got there, what holds that score up, what the measurement can't tell you, and when to pick each of the others.

  • Light ALA: which parts of ALA pay for themselves

    Seven variants of the same Phoenix app went through the same ten requirement changes, each made by an agent and graded. Strict ALA cost 1.34× the conventional app per change; a light form built up from the conventional app cost 1.07×, broke as few existing tests as strict ALA, and read best. Here is the curve, its knee, the four parts of ALA below it, and the variant that holds them.

  • Ash in an ALA app: which pieces fit, which don't, and where the rest goes

    Ash is a resource-centric framework that derives everything from a declared model, which is the shape Spray argues against. Here is each Ash piece read against the checklist, the layer it lands in, and how notifications, Ash's PubSub notifier and AshOban can be used without a resource deciding what happens next.

Building from Scratch with ALA

Taking ALA Designs to 100

What a Phoenix team keeps, adopting V50: the router, LiveView, handle_event, streams, PubSub, function components and ExUnit, all as they were. LiveView itself supplies the long-lived process and the surface the wiring lives on.

What it learns: state modules as functions that return the new state and a list of named outputs, and wire/3 clauses on the page that route every output. Both are plain Elixir. The new habit is that the page is a composition rather than a controller with state, so an outcome goes through wire instead of across modules inside handle_event; and logic that lived in contexts moves into state modules and a foundation layer.

Variant Full score, rules met, familiarity Wiring written as Feature state in LiveView relays between components
V50, plain LiveView * 100, 10/10, 5/5 wire/3 clauses on the page; every hop traced under the suite, which fails on an output never routed page assigns none
V51, plain stories 100, 10/10, 4/5 story modules (a Features layer) on V50's runner, wired by page clauses; every hop traced under the suite page assigns none
V51B, shared editing story * 100, 10/10, 4/5 V51's story modules, with one EditLines story placed by both pages and a pricing story beside it on each; every hop traced under the suite page assigns none
V59, light ALA * light reading, 7/7 adopted, 5/5 none: pages call their parts, built once by a composition root per page; no ports contexts, page assigns none

* Recommended: V50 as the one to start from; V51B as the fullest expression of ALA in Elixir so far; V59 as light ALA, which in the change runs cost about what conventional Phoenix costs.

  • V50, plain LiveView: 100 at familiarity 5, with no relays *

    V48 without named instances: its store work is given to the wiring as plain function captures, the payment is LiveView's own start_async, and the runner is two functions. Every update runs inside one handle_event, with no LiveComponents relaying through the page. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (5/5)

  • V51, plain stories: Spray's Features layer, and every lint rule at its strictest

    V50 split along user stories, with the cart's state split into smaller abstractions. A story is a module of plain functions run by V50's two-function runner, and the page wires stories. The first variant to meet all ten checked rules under --super-strict. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (4/5)

  • V51B, a shared editing story: one story for the cart and the order *

    V51 with one editing story placed by both pages, each handing in its row and its own pricing story. An alternative organisation of the Features layer, kept beside V51 so the two shapes can be compared. The running trace was first built here and now lives in V50 and V51 too. ALA Checklist Score: 100 (Lint, 10 of 10 rules met, with a layer map) 100 (Full). Familiarity (4/5)

  • V59, light ALA: twelve rules on plain Phoenix *

    The light ALA variant: conventional Phoenix with four layers, calibration at the top, rules as named pure modules, configuration and session values passed once as structs, guards in the writer, one composition root per page, and no ports or wiring. What each rule looks like in the code, how to read a page, and the linter settings that keep it honest while you work. Lint with V59's settings: 100 at every tier, the seven adopted rules met under --strict. 175 tests, 99.61% coverage.

Archived Design Variants

Designs whose lesson a variant above carries in full: V50's siblings and forerunners (V49, V48, V46, V47, V45, V39-max, V41-max), earlier designs that score under 95 on the full ALA Checklist walk, and V38-max. Each post records its scores.

  • V49, plain components: 100 at familiarity 5

    V41-max without its route table. Feature panels are LiveComponents, the page's wiring is plain handle_info and handle_async clauses, and everything it calls is LiveView's own API. Store work whose answer goes to another panel runs as a LiveView task, and the page names each panel. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (5/5)

  • V48, plain clauses: 100 at familiarity 4

    V45 with only the two changes Spray's stricter readings asked for: the coded state modules named for what they are, and a generic record form instead of the generated FormComponent. No Features layer, because its pages are under Spray's size limit. The test of whether a full score has to cost familiarity. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (4/5)

  • V46, feature stories: Spray's Features layer in a LiveView app

    V45 with a real Features layer. Each page composes user stories, modules that instantiate, configure and wire domain abstractions and lay out their own view, and the page wires the stories. A generic record form replaces the generated FormComponent. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (3/5)

  • V47, typed story maps: Spray's features, typed ports, and a diagram that runs

    V39-max with Spray's Features layer: each story's wiring is a bindings map, the page's map links the stories, every port is typed, and the whole composition is checked when a page mounts and drawn from the value that runs. ALA Checklist Score: 100 (Lint, 10 of 10 rules met) 100 (Full). Familiarity (3/5)

  • V45, checked clauses: 100, zero hops, safe and familiar wiring

    A design aimed at all four at once: a full ALA Checklist score, no message hops, a codebase no larger than the other full variants, and wiring that is safe without being unfamiliar. Plain LiveView pages whose wire/3 clauses are the wiring, named store-work instances so no clause reads assigns, a one-line coverage test per page, and an optional compile-time check. ALA Checklist Score: 99 (Lint, 8 of 10 rules met) 97 (Full). Familiarity (4/5)

  • V39-max: bound ports at 100

    V39's one-map-per-page design, changed until a rule-by-rule walk of the ALA Checklist finds nothing to deduct. Store work moves into configured domain instances behind a paradigm port, mount becomes an event on the diagram, and a test checks every port is bound or grounded. Zero message hops. ALA Checklist Score: 99 (Lint, 8 of 10 rules met) 97 (Full). Familiarity (3/5)

  • V41-max: feature components at 100

    V41's LiveComponent panels, changed until a rule-by-rule walk of the ALA Checklist found nothing to deduct but the one message hop the design costs. A later rescore found its panels doing their own I/O; taking that out brought it back to 100. Every word comes from the page, configuration is built once, and one route table per page is the wiring. ALA Checklist Score: 99 (Lint, 8 of 10 rules met) 95 (Full). Familiarity (4/5)

  • V38-max: a plain LiveView at 100

    V38's conventional storefront, built out to the full storefront and portal requirements and changed until a rule-by-rule walk of the ALA Checklist finds nothing to deduct. Each page is still one plain LiveView module with no binder, route table or components: 44 wire/3 clauses are the wiring, one per port, and a 56-line runner folds each feature's outputs through them. Zero message hops. ALA Checklist Score: 99 (Lint, 8 of 10 rules met) 97 (Full). Familiarity (4/5)

  • V36, the vernacular core: ALA that reads like ordinary Phoenix

    A LiveView design that any Phoenix developer understands after one example, yet holds zero feature-to-feature coupling by discipline rather than machinery. ALA Checklist Score: 87 (Lint, 8 of 10 rules met) 91 (Full). Familiarity (5/5)

  • V38, lint-guided evolution: making a conventional app ALA

    Instead of designing an ALA architecture up front, start from an ordinary Phoenix app and let the ALA Checklist and ala_lint guide it there, one small change at a time. ALA Checklist Score: 95 (Lint, 5 of 10 rules met) 84 (Full). Familiarity (5/5)

  • V35, composed inputs on a committed-codegen spine

    A LiveView variant where the page's wiring diagram is a data file, the glue is generated and committed with CI failing on drift, and the sneakiest peer dependency in a multi-feature page, a feature reading another's state, is made impossible instead of lint-able. ALA Checklist Score: 90 (Lint, 5 of 10 rules met) 75 (Full). Familiarity (3/5)

  • V39, bound ports: the page is one map

    A LiveView variant where every feature is a pure function that announces results on named ports, and each page is a single map saying where those ports land. ALA Checklist Score: 93 (Lint, 5 of 10 rules met) 79 (Full). Familiarity (4/5)

  • V40, circuit instances: Spray's diagram, run as data

    The most literal Spray shape built at full size: the page assembles a circuit of feature instances and sinks, UI components own their events and push into named inputs, and nothing on the page decides anything. ALA Checklist Score: 91 (Lint, 5 of 10 rules met) 77 (Full). Familiarity (2/5)

  • V41, feature components: ALA in the shape phx.gen.live already gives you

    Each feature is a LiveComponent instance that owns its state, stream, events and store writes; the page places and configures the instances (and, since a revision, their stores and domain rules) and routes what they announce. Eighteen lines of paradigm, nothing new to learn. ALA Checklist Score: 93 (Lint, 4 of 10 rules met) 84 (Full). Familiarity (5/5)

  • V42, typed circuit: the diagram declared, checked, and drawn

    V40's circuit of instances, made strict: every port declares its type, every wire and unused output is checked when the page mounts, each page's circuit lives in a diagram module drawn from the value that runs, and no closure hides a call. ALA Checklist Score: 93 (Lint, 5 of 10 rules met) 81 (Full). Familiarity (2/5)

ALA in Ruby on Rails

  • The ALA thermometer in Ruby

    Spray's thermometer at its last rung, in plain Ruby: instances configured by the application, a dataflow chain from an ADC to a display, the display inside a window, a tick that drives it. 251 lines, every output wired, and 100 on the Ruby linter at its strictest.

  • The coffee maker in Ruby: Spray's diagram, wired as objects

    Robert Martin's Mark IV coffee maker in plain Ruby, built the way Spray draws it: three domain abstractions, an AND gate, rising edges and a state machine, wired port to port in one application class with no if statements. Lint: 100 at every tier, 10 of 10 rules met.

  • How close can a Ruby on Rails app come to ideal ALA?

    Spray's application layer has no if statements and no data handling, and his classes have ports and no associations. Rails hands a controller params, a session and a request that ends; Ruby hands it mutable objects and no interfaces. Which departures does the framework force, which does the language force, which are habits, and how far did two Rails designs get? One reaches every rule the linter checks at its strictest.

Building from Scratch with ALA

Taking ALA Designs to 100

What a Rails team keeps, adopting V06: controllers, routes, Active Record models, partials, Turbo Streams, Stimulus, Minitest and Capybara, all as they were. A controller action calls one method on a screen object and redirects or renders.

What it learns: a screen class per page, a method that returns a Hash of named outcomes, and one case that routes them, each a shape a Rails developer has written in a service object. The new habit is that the composition is the only place two objects meet: a model holds persistence only, so a model method becomes a method on a plain value class returning a Hash, and the reflex of calling one model from another has to go.

Variant Lint (default / strict / super-strict), rules met, familiarity Wiring written as Feature state in
V06, plain Rails * 100 / 100 / 100, 10/10, 5/5 no port vocabulary: an input is a method, its outputs are the Hash it returns, a screen wires with one case [part, output]; a thirteen-line trace fails the suite on an output never routed values per request, per-feature tables behind store abstractions
V07, plain features 100 / 100 / 100, 10/10, 4/5 V06's case, plus a Features layer: a feature is a class with the same wire, and collect/out make its parts' outputs its own; one feature placed by the cart and the portal values per request, per-feature tables behind store abstractions
V05, shared feature * 100 / 100 / 100, 10/10, 3/5 a Features layer: OrderLines wired inside, placed by the cart and portal screens with their own links, window and totals; a running trace fails the suite on a wire that never carried anything the cart and the checkout kept, the job delivering into it; the portal per request

* Recommended: V06 as the one to start from; V05 as the fullest expression of ALA in Ruby so far.

  • V06 in Rails, plain Rails: the same design with no port vocabulary at all *

    V03 written in the Ruby a Rails developer already reads, the way V50 did for Phoenix. An input is a method, its outputs are the Hash it returns, a screen wires with one case over [part, output], and a pull is an argument. The Foundation went from ninety lines to none, a thirteen-line trace fails the suite on an output never routed, and the linter learned two shapes to read it. Lint: 100 at every tier, no finding; 57 + 5 tests (since 2026-10-19: two accepted lines; 79 + 7 tests; since 2026-10-21, with outside change as a paradigm: 85 + 11 tests). Familiarity (5/5)

  • V07 in Rails, plain features: Spray's Features layer with two more words

    V06 with the Features layer added in its own plain Ruby. A feature is a class with the wire a screen has; collect and out make its parts' outputs its own; one feature is placed by the cart and the portal with their own links and undo windows. The drawing opens a feature, the trace covers its inside, and the linter learned two small things. Lint: 100 at every tier, no finding; 60 + 5 tests (since 2026-10-19: one accepted line; 86 + 7 tests; since 2026-10-21, with outside change as a paradigm: 100 + 9 tests). Familiarity (4/5)

  • V05 in Rails, a shared feature: one order-lines feature placed by two pages *

    V04 with Spray's Features layer between the application and the domain, and one feature in it: the lines of an order with an undoable removal, wired inside and exposed as ports, placed by the cart page inside its long-lived composition and by the portal per request. Then a running trace: after the full suite every wire must have carried something, and the drawing shows which did. The checkout is kept too, with the job delivering into it. Lint: 100 at every tier; 70 + 5 tests (86 + 7 since 2026-10-19; 108 + 9 since 2026-10-21, when outside change became a paradigm). Familiarity (3/5)

Archived Design Variants

Designs whose lesson a variant above carries in full: V01 is the before picture, V02 is covered by V03, V03's pure core and Turbo Stream patches are carried by V05, V06 and V07, and V04 is a step on the way to V05. Each post records its scores.

  • V03 in Rails, a pure core and streams: values that pull through ports, and changes that answer with patches

    V02 with two techniques borrowed from the Elixir variants: the cart's lists are values that pull their lines through a port and write every change through a wired store, so the domain runs without Postgres; and a change on the cart answers a Turbo request with the patches its outputs made instead of a redirect. Lint: 100 at every tier, 10 of 10 rules met; 57 + 5 tests (since 2026-10-19: 100 / 99 / 99 with the clone check; 58 + 5 tests). Familiarity (4/5)

  • V04 in Rails, a long-lived composition: wired once per cart, with Puma's threads handled at wiring time

    The one thing a Rails ALA app had not done: the cart page's composition is built once per cart and kept across requests. An execution model runs each request under the composition's own lock (Spray's arbitrator, decided where instances are wired), and reloads the values only when the cart's write stamp moved behind its back. Lint: 100 at every tier with six accepted lines; 66 + 5 tests (since 2026-10-19: 100 / 99 / 99 with the clone check; 67 + 5 tests). Familiarity (3/5)

  • V02 in Rails, wired rows: every edge drops, and the pages hold no logic

    V01 taken the rest of the way: a declared five-layer map with rules and UI elements under the domain, product data through a pull port instead of an association, rows that carry their own URLs so pages render collections, names that flow down. Lint: 100 at every tier, 10 of 10 rules met; 55 tests including a browser suite. Familiarity (4/5)

  • V01 in Rails, wired screens: Spray's object wiring, one composition per request

    The storefront and portal rebuilt in Rails 8 with Hotwire: a screen class per page that builds, configures and wires domain abstractions port to port, controllers that push one input, per-feature tables keyed by cart id, broadcasts and a job wired as ports. Lint: 66 (default), 53 (super-strict); 6 of 10 rules met. Familiarity (4/5)