V01 in Rails, wired screens: Spray's object wiring, one composition per request
The Elixir variants took a LiveView storefront from a conventional app to designs that score 100 on the checklist. This is the first Ruby one: the same requirements, a catalogue with live validation, a cart with undo and saved items and a wishlist, an asynchronous checkout, and a bulk-order portal, built as a Rails 8.1 app with Hotwire against the Ruby edition of the checklist. The brief was to prefer the choice a Rails team already knows unless a less familiar one served the design better.
Two things make Rails different from LiveView for ALA. There is no long-lived process per page, so a composition can’t be built once and kept; and the natural wiring form is Spray’s own, objects with ports, because Ruby has classes and the checklist’s Foundation gives them ports.
A screen is a composition, built per request
Each page has a class under Screens::. Its constructor creates the page’s domain instances, configures them from Screens::Store (the calibration: rates, codes, tiers, words), and wires them. Nothing has run yet. The controller then pushes one input and either redirects with what the screen said or renders what landed:
class CartItemsController < ApplicationController
def destroy
screen.input_port(:remove).push(params[:id].to_i)
back_to_cart
end
end
module Screens
class Cart
include Foundation::Ports
include DomainAbstractions
input(:remove, ProgrammingParadigms::DataFlow) { |item_id| @lines.input_port(:remove).push(item_id) }
def initialize(cart_id:)
@lines = CartLines.new(lines: CartItem, cart_id:, stock_rule: StockStatus.new(low_at: Store::LOW_STOCK_AT))
@undo = Undo.new(lines: CartItem, cart_id:, window: Store::UNDO_WINDOW)
@totals = CartTotals.new(shipping:, gift_wrap: CalculateGiftWrapCost.new(unit: Store::GIFT_WRAP_CENTS))
@lines.on(:rows) { @rows = _1 }
@lines.wire_to(@totals, from: :contents, to: :contents)
@lines.wire_to(@undo, from: :removed, to: :capture)
@undo.on(:restored) { say :notice, "Item restored" }
@totals.on(:summary) { @summary = _1 }
end
end
end
Because the composition is rebuilt per request, every instance that holds state keeps it in a store it is configured with: CartLines on the cart_items table, Undo on the same table’s removed_at column, CheckoutFlow on a checkouts table that holds the step. Puma serves requests on threads and no instance outlives one, which is Spray’s one-thread-per-stateful-instance (§3.9) for free.
Where LiveView’s process state went
| In the Elixir variants | Here |
|---|---|
| gift-wrap marks in the cart’s state | a column on cart_items |
| the undo offer and its timer | removed_at; a Stimulus countdown posts expire; the next load purges anything past the window |
| promo code, shipping method, checkout step, PO step | one small table per feature, keyed by cart id (R10) |
the payment task and handle_async | Foundation::PushLater, an Active Job wired as a port: it rebuilds the screen by name and pushes the charge input; a LiveUpdate sink replaces the status element, which carries a Stimulus visit to the success page |
| PubSub stock facts re-rendering each row | LiveUpdate broadcasts the stock badge to every element marked for that product |
| the active tab | a Stimulus controller; UI state only |
Broadcasts are wired from screens, never from model callbacks. Screens::Catalog wires Records.saved to a LiveUpdate; Screens::Checkout wires SettleOrder.stock_changed to one. No after_commit anywhere.
The Rails choices, against the checklist
- Controllers forward; screens compose. The two places a controller branches (
if screen.saved,if screen.step == :payment) route an outcome to a response, which R11 reads as routing. - Models are persistence, one per feature. Small data-only methods (
CartItem.add,Product.decrement_stock,Order.place), no feature rules. Address and PO validations sit onCheckoutandOrderSubmissionwith contexts, their messages inconfig/locales. - Changes redirect; Turbo morphs. Every change is a
button_toor a small form that redirects to the page, which the layout refreshes by morph. The most ordinary Rails shape, one-line controllers, and a full render per change that Turbo hides. It departs from the requirement’s “streams, no full re-render” in mechanism, not in behaviour. - Live validation posts the form to a
validateaction that answers a Turbo Stream replacing the form. Rails 8’s per-form CSRF tokens meant the fetch has to send the page’s token. - No DI container, no service objects, no concerns on models.
- One
cart_itemstable serves both the storefront and the portal, as the lines abstraction both build on (V51’sLines). A stricter R10 reading would give the portal its own.
What the linter found
The 48 integration tests ported from the Elixir acceptance suites pass, and the pages were exercised by hand in a browser. Then the Ruby linter ran:
| tier | score | rules met | functions clean |
|---|---|---|---|
| default | 66 (C) | 6 of 10 | 192/204 (94%) |
--strict | 61 | 5 of 10 | 192/204 |
--super-strict | 53 (D) | 4 of 10 | 182/204 (89%) |
The density is low and concentrated: 18 of the scored findings are R1, in three kinds, and all three are real.
- Component partials rendering or calling peers.
_cart_linerenderscomponents/product_lineandstock_badge; four components call theLiveTargetsHelperthat names DOM targets. In the declared map every component sits in the domain layer, so each is a cross-peer edge. The checklist’s answer is that the page places both; the honest alternative is to declare that a product line and a stock badge are more general than a cart line, which they are. - Stateful abstractions calling pure rules.
CartTotalsandOrderTotalscallPricing;CheckoutFlowcallsCheckStock. The design doc called these “rules one layer down”, but the layer map had one domain layer, so they are peers. The map didn’t say what the prose assumed. - Foundation reaching up.
LiveUpdateandPushLaterbuildDataFlowports, andLiveUpdate.componentrenders throughApplicationController. Execution models that use the paradigms belong beside them, not under them.
Then three R10 findings, belongs_to :product on every line table (the storefront’s lines read the catalogue’s columns through the association); two R5 names agreed between a screen and a component ("checkout_status", "modal"); and one R3 literal that is intrinsic. Under --super-strict, fifteen R11 findings: two branches inside wiring blocks, the session fallbacks’ ||, and loops and persisted? ternaries in page templates.
None of it was applied here. Each finding, with the options, is in LINT_NOTES.md, and V02 is the design that takes them.
The wiring, drawn from the built graph
The screens can draw themselves. Foundation::Ports records each wire as it is made, and ProgrammingParadigms::Drawing.mermaid(screen) walks the parts of a built screen, so the picture can’t drift from the code (R8’s technique). The cart:
flowchart LR
screen[[Screens::Cart]]
lines[lines: CartLines]
undo[undo: Undo]
saved[saved: SavedItems]
wishlist[wishlist: Wishlist]
pricing[pricing: PricingChoices]
totals[totals: CartTotals]
lines -- rows --> screen
lines -- contents → contents --> totals
lines -- removed → capture --> undo
lines -- saved → stash --> saved
lines -- saved --> screen
lines -- line --> screen
undo -- pending --> screen
undo -- restored --> screen
saved -- rows --> screen
saved -- count --> screen
saved -- moved → receive --> lines
saved -- moved --> screen
wishlist -- rows --> screen
wishlist -- count --> screen
wishlist -- ids --> screen
wishlist -- added --> screen
wishlist -- dropped --> screen
wishlist -- taken → receive --> lines
wishlist -- taken --> screen
pricing -- discount → discount --> totals
pricing -- shipping_method → shipping_method --> totals
pricing -- promo_applied --> screen
pricing -- promo_rejected --> screen
totals -- summary --> screen
An edge to screen is an output the composition lands in a field or turns into a flash with on. rails ala:diagrams writes one of these per screen.
What it costs
- A page needs a screen class plus small controllers, so a feature touches more files than
rails g scaffoldwould. The screens are 60 to 90 lines; the controllers 10 to 40. wire_toandonare a vocabulary a Rails team hasn’t met. Everything else is stock Rails: models, controllers, partials, Stimulus, Active Job, Turbo Streams. That’s why I put familiarity at 4.- The undo window depends on the browser posting
expire; without it the removal is finalised on the next load, and the banner stays until then. - Two bugs the browser found later, both fixed in V01 and V02: the live-validation fetch forwarded the form’s
_method=patchto a POST-only route, and the portal’s submit route was POST whileform_with model:sends PATCH for a persisted record. The integration tests posted directly and never saw either.
The code is in ala_variants_ruby/v01-wired-screens.