Capstone: One Line, Six Layers Grows Up

What We'll Build

Tutorial 00 introduced the chapter anchor expression — one line of Higher-Kinded-J that touched every layer of the library. By the time we reach this capstone we have learned each layer in depth: the Effect Path API, optics, expression comprehensions, structured concurrency, resilience patterns. The capstone is the same expression, grown up to handle a realistic order workflow:

findOrder(id)
    .toEitherPath(OrderError.NOT_FOUND)
    .map(o -> itemsLens.modify(this::recompute, o))
    .via(this::reserveInventory)
    .via(this::save)
    .run();

Same six layers. Same mental model. One expression.

Duration: ~30 minutes | Tutorials: 1 (capstone) | Exercises: 7

Prerequisites: complete the Foundations Journey, the Effect API Journey, and at least one of Optics: Lens & Prism or Concurrency: VTask.

Where This Fits in the Bigger Picture

The capstone is the single best demonstration that the chapter material composes. We use the One Line, Six Layers expression as the through-line, applied to a realistic order pipeline that touches every journey:

TokenCapstone exerciseJourney
find(id)E1 lift to EitherPathEffect API
.toEitherPath(...)E1 natural transformationFoundations + Effect API
.map(itemsLens.modify(...))E2 bulk updateOptics
.via(reserveInventory)E3 chain dependent stepsFoundations Monad
.via(save)E3 chain dependent stepsFoundations Monad
.run()E3 dispatchEffect API
Full expressionE4 assembleevery journey
Resilience layerE5 circuit breaker + retryResilience
ForPath spellingE6 same pipeline, comprehension formExpression
Graceful degradationE7 recover with a defaultEffect API

What We'll Learn

  • How the patterns from each journey compose into one realistic workflow
  • Two equivalent spellings of the same pipeline (fluent chain and ForPath comprehension)
  • Where to add resilience without disrupting the rest of the pipeline
  • Where graceful degradation belongs (recover early; downstream steps proceed normally)

How the Tutorial Works

A single test file with 7 exercises and a matching solution file. Exercises 1-3 build the pipeline incrementally; exercise 4 assembles them all; exercises 5-7 add resilience, an alternative spelling, and recovery.

./gradlew :hkj-examples:tutorialTest --tests "*TutorialCapstone_OneLineSixLayersGrowsUp*"
./gradlew :hkj-examples:test --tests "*TutorialCapstone_OneLineSixLayersGrowsUp_Solution*"

Where to Next

  • Read the production order example: hkj-examples/src/main/java/org/higherkindedj/example/order. Same shape, more services.
  • Replace the in-memory repo with a real database access via VTaskPath, add a saga around payment + shipment, log every step through an audit interpreter (Effect Handlers journey).
  • Use OpticsSpecInterfaces (Optics Tutorial 16) to lift third-party domain objects (Jackson POJOs, jOOQ records) into the same pipeline.

Previous: Effect Handlers Journey Next: Foundations chapter — the theory underneath