F5 · chapter overview
Pragmatic programming
Everything so far has been parts; this chapter builds a product. F5 is a pragmatic, end-to-end build of the Portal engine — the framework-free core that holds the Portal’s domain logic — applying the working practices of pragmatic programming in Elixir: stand it up behind a thin web server so it runs from day one, model the domain in plain structs and contexts, fire a tracer bullet through one real use case, guard it with contracts, separate commands from queries, decide where state lives, and test the pure core. By the last module the engine is assembled behind a clean facade and mounted in a LiveView sketch — ready to wire into Phoenix LiveView in F6.
Nine modules, one product. Each applies a pragmatic technique to the same growing engine, so by the end you have not nine demos but one coherent Portal engine with a UI-ready boundary.
The system we’re building
Before the modules, three short design pages lay out the engine the whole chapter delivers — its structure, its data, and how it moves. Read them first; every module below builds one piece of this design.
The Portal engine blueprint
The whole engine at a glance: a framework-free core between the F4 store below and the F6 LiveView UI above, and which module builds each layer.
The domain model
The entities and bounded contexts the engine owns — Accounts, Catalog, Learning — modeled as structs keyed by branded ids.
The command & event flow
How one use case moves through the engine: command, contract, event, state, query — the read/write split the UI will see.
The chapter arc
Read it in order: each module leaves the engine more finished than it found it. The early modules give it a shape that is cheap to change — a decoupled core, a modeled domain, a thin slice that runs end to end. The middle modules make it trustworthy — contracts, an explicit command/query/event flow, a decided home for state. The last modules make it usable from the outside — tested, with ports and a facade — and the lab mounts that facade behind a LiveView sketch. The chapter is `live`; the modules below are in production.
Nine modules · one product, the Portal engine
Pragmatism is not a topic; it is the discipline of building one thing well. This chapter spends every module on the same engine, so the techniques land as habits, not trivia.
Module navigation
The modules below link to their hubs and deep dives, so the whole build path is visible from here. The arc is the build order — start at F5.01.
Start thin: a running Portal from day one
Stand the Portal up behind a minimal Elixir web server now, and plan the path to Phoenix.
- F5.01.1The development roadmap
- F5.01.2A thin web server in Elixir
- F5.01.3A web layer built for replacement
Modeling the Portal domain
The Portal’s entities as structs and bounded contexts: Accounts, Catalog, Learning.
- F5.02.1Structs & typespecs
- F5.02.2Bounded contexts
- F5.02.3A context’s public API
Tracer bullets: a walking skeleton
Build one use case end to end first: enroll a learner, then deliver the first lesson.
- F5.03.1Tracer bullets vs prototypes
- F5.03.2The walking skeleton
- F5.03.3Iterating the slice
Design by contract
Preconditions, postconditions, and invariants on the engine’s commands.
- F5.04.1Preconditions, postconditions & invariants
- F5.04.2Assertions in Elixir
- F5.04.3Failing fast
Commands, queries & events
Separate writes from reads; model every change to the engine as a domain event.
- F5.05.1Command/query separation
- F5.05.2Domain events
- F5.05.3The engine as a reducer
Where engine state lives
Choosing where state lives — GenServer, Agent, ETS — and the process boundary around it.
- F5.06.1Choosing where state lives
- F5.06.2The engine GenServer
- F5.06.3Supervision
Pragmatic testing
Testing the pure core, property-based tests, and contracts as tests.
- F5.07.1Testing the pure core
- F5.07.2Property-based testing
- F5.07.3Contract tests
Boundaries & integration seams
Ports, adapters, and the engine facade the UI will call — with error shapes the UI can render.
- F5.08.1Ports & adapters
- F5.08.2The engine facade
- F5.08.3Error contracts for the UI
Lab: the Portal engine, LiveView-ready
Assemble the engine facade and mount it behind a LiveView sketch — ready for F6.
- F5.09.1The engine facade end to end
- F5.09.2A LiveView mount sketch
- F5.09.3What ships in F6
The chapter opens with F5.01 — Pragmatic foundations and closes with the F5.09 engine lab. It builds on F4 — Algorithms & Data Structures — the branded CHAMP store from F4 is the kind of component the engine wraps — and hands its LiveView-ready facade to F6, the Phoenix chapter, where the UI is built.