Local FastAPI UI

Local UI Architecture

Architecture

Internal reference for the local UI running from this repo.
Stable as of May 17, 2026

Layer Map

LayerPurposeCurrent Examples
ui/routesRender page shells and section tabs.reex.py, pdrs.py, rbs.py, roboticex.py, docs.py
ui/apiOwn JSON endpoints for runtime and mutations.buyers.py, sellers.py, runtime.py
ui/actionsOwn mutation adapters against portal helpers.buyer_mutations.py, seller_mutations.py
ui/dataOwn DB reads, portal reads, and parsing for read models.member_accounts.py, reex_buyers.py, reex_sellers.py
ui/domainOwn shared aggregation and business summaries.overview.py
ui/servicesOrchestrate read flows for pages.reex_service.py, roboticex_service.py
ui/viewmodelsShape stable template contracts.sellers.py, buyers.py
ui/templatesPresentation only.shared components and section templates

Request Flow

  1. Browser hits a page route such as /ctx/reex?tab=sellerTable.
  2. The route chooses the content template and asks a service for read data.
  3. The service pulls normalized rows from ui/data and summaries from ui/domain.
  4. The route passes those rows through ui/viewmodels when a stable page contract is needed.
  5. The template renders shared components from ui/templates/components.

Mutation Flow

  1. UI forms post to /ctx/api/sellers/... or /ctx/api/buyers/....
  2. The API layer validates payloads and enforces runtime gating where required.
  3. The API delegates to handler registries in ui/actions.
  4. The action layer calls exchange-specific portal helpers and returns a normalized result.
  5. The frontend redirects back to the current page with a success or error banner.

Design Rules

  • Do not put SQL or HTML parsing in ui/routes or ui/templates.
  • Do not add new page-bound mutation routes under section files.
  • New read integrations should land in ui/data first.
  • New mutations should land in ui/actions first.
  • Shared presentation should prefer ui/viewmodels plus component templates over exchange-specific branching in Jinja.

Current Gaps

  • Read-side buyer enrichment for RBS and Roboticex still lives in service modules and can move into ui/data later.
  • Roboticex overview uses a buyer-specific shape and is not yet normalized into the shared overview component family.
  • There is no dedicated architecture navigation index yet beyond this page.