Auction Detail Controller Boundary
Purpose
This note documents the Sprint 05 boundary cleanup for the auction detail flow in apps/web.
Loading module
Resolving locale, route permissions, and workspace projection.
Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 10_normative | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: GOVERNANCE_ADMIN
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
This note documents the Sprint 05 boundary cleanup for the auction detail flow in apps/web.
The goal of this layer is not to make bidder mutations look durable. The goal is to make the current truth model explicit in code:
canonicalRead remains the visible source for auction detail/list readsUI-FIRST and compatibility-backedTop-level entry:
Controller / view-model layer:
Presentation modules from Sprint 04:
apps/web/src/portal/components/auctionDetail/AuctionReadPresentation.tsxapps/web/src/portal/components/auctionDetail/AuctionDeliveryOptionsPanel.tsxapps/web/src/portal/components/auctionDetail/AuctionBidActionCluster.tsxapps/web/src/portal/components/auctionDetail/AuctionBuyNowAction.tsxapps/web/src/portal/components/auctionDetail/AuctionFulfillmentPanel.tsxapps/web/src/portal/components/auctionDetail/AuctionCompatibilityNotice.tsxRelated cross-sprint boundaries:
apps/web/src/ui/auctions/canonicalRead/portalReadBoundary.tsapps/web/src/ui/auctions/compatibility/sessionAuctionMutationPort.tsapps/web/src/ui/auctions/futureDurable/auctionMutationPort.tsapps/web/src/ui/auctions/session/bidOverlay.tsapps/web/src/ui/auctions/session/fulfillmentOverlay.tsapps/web/src/ui/auctions/session/transportSelectionOverlay.tsAuctionDetailClient.tsxStatus: MIXED, but intentionally thin after Sprint 05.
Owns:
It is now a shell/orchestrator entry point, not the place where eligibility, overlay merge, or compatibility write logic is implemented.
useAuctionDetailController.tsxStatus: UI-FIRST controller/view-model layer.
Owns:
It is intentionally the place where current truth is concentrated:
detailuseAuctionSessionOverlays.tsStatus: UI-FIRST.
Owns:
This is the explicit session/local merge layer for the detail controller.
useAuctionBidderIdentity.tsStatus: MIXED.
Owns:
useCurrentUser()getMyStakeholderContext()This hook keeps session/account/stakeholder identity shaping out of the visual detail component.
compatibilityActionAdapter.tsStatus: UI-FIRST.
Owns:
It currently maps to:
This is intentionally named as compatibility, not service, gateway, or API mutation.
AuctionDetailClientSprint 05 extracted these responsibilities from the top-level component:
This means new engineers and future AI agents no longer need to read a single giant client component to find:
Inside useAuctionDetailController.tsx:
Inside AuctionDetailClient.tsx:
This centralization is intentional for now. Splitting further before a real durable mutation path exists would risk scattering the same UI-first truth across too many modules.
Status: REAL / MIXED depending on upstream source, unchanged by this sprint.
Status: UI-FIRST.
These still flow through the compatibility adapter to the session-backed mutation port.
Status: UI-FIRST.
These remain explicit and isolated under ui/auctions/session/*.
Status: SHELL.
The durable seam still exists under:
Sprint 05 did not implement it. The controller boundary now makes the eventual swap point much clearer.
When a real bidder mutation backend is implemented later, the intended change point is:
AuctionDetailClient.tsx unchanged or nearly unchangeduseAuctionSessionOverlays.ts if durable optimistic/revalidation behavior replaces session overlaysThat is the main value of this sprint: the swap point is now explicit instead of buried inside a very large UI component.