Source pin: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. Guide: architecture.
New detail slide: architecture-read-handoffs, following
architecture-owning-boundaries. This is a candidate, not an accepted
benchmark.
Visual thesis: three quiet, named responsibility lanes in cream and ink make the shared adapter's composition work the focal point; terracotta marks its ownership, while labeled arrows carry requests and returned data.
Content plan: retain the existing conceptual overview, including its Metis and
route-namespace qualifications; zoom into Tara's getHomeCards call; follow the
request, three concurrent reads, their successful fulfillment and the composed
return; then distinguish runtime schemas and the separate BFF partial-failure
contract in the following architecture material. The example is a successful
library call, not a captured member session or a universal service topology.
Interaction thesis: retain the existing slide entrance, source disclosure and workspace transition, respecting reduced motion. All owners, directions and conditions remain available without animation. Narrow views name both endpoints on every exchange; print keeps the complete static relationship.
Source review and bounds#
libs/oshun/domain-tara/src/canonical-adapter.tsowns thegetHomeCardsorchestration: it starts continuation, course-progress and favorite reads inPromise.all, passes their values tocomposeTaraHomeCards, and returns the result. The three requests use the supplieduserId; favorites default to a limit of three and offset zero. That is an input convention, not proof of authenticated identity.- The same factory accepts an injected
apiAdapteror creates its HTTP client. Neither choice implies that the library is a separate deployed service.apps/oshun/bff/src/adapters/tara-read-adapters.tssupplies a concrete injected bridge to the BFF's configured Tara domain adapter. The bridge does not select or prove a deployed transport by itself. libs/oshun/domain-tara/src/client.tsbuilds absolute/v1/oshun/...paths against a configured base URL. A path prefix in that base URL is not preserved. The default client adds an accept header and configured headers; the caller must supply the appropriate authentication configuration. JSON decoding is a type assertion, not response-schema validation.- A rejected read rejects
getHomeCards; this method does not return the BFF's partial-failure envelope or cancel the other started reads. The happy-path arrow labeled “All three fulfilled” is conditional, not a promise of success.
Executable source evidence must exercise the immutable orchestration with controlled pending/rejected API promises and the actual HTTP-client boundary. Injected composition spies establish handoff arguments and timing, not the correctness of downstream card models, deployed authorization or persistence. Keep those exclusions explicit in the evidence.
Semantic and visual contract#
Use ownership-handoffs for an ordered, explicitly scoped example with named
owners and labeled exchanges. The owner count follows the source; there is no
three-lane quota. Each owner has a stable ID, responsibility and reading order.
Each exchange has its own stable ID, declared endpoints, kind and label;
optional detail must add information rather than repeat the direction or label.
The three source-read names need that detail; redundant request/return prose
does not. Repeated exchanges between two owners are legitimate. Reject missing
endpoints, duplicate exchange IDs, unlabeled directions and orphaned owners.
This is not a general branch, distributed trace or elapsed-time chart.
Desktop lanes retain stable owner positions. Requests and returns route between owner centers, with direction visible in arrowheads and nonvisual named endpoints. Narrow layouts show those endpoint names visibly. Header rules identify responsibility lanes; arrow lengths identify endpoints, not durations. At narrow widths, reflow to named exchanges while retaining the owner/responsibility key. Labels remain live HTML text, not a scaled SVG canvas. Test repeated exchanges, long uneven names, both directions, keyboard navigation, narration, reduced motion and PDF.
Neutral reader tasks: Who starts the three reads? What must happen before the composition is returned? If one read rejects, what does the caller receive? Does this establish that a member was authenticated or a screen rendered? Real willing-reader sessions remain pending; automation and model review cannot substitute for them.