UI API Auth Boundaries

Summary

UI/API/auth boundaries are the shared explanation for how operator intent moves from a route to a service without letting page files own business state. Domain threads should link here when explaining route shells, API adapters, auth, tenant context, actor context, read models, and action descriptors.

Reader Question

How does an interactive surface show operational state and collect user intent without bypassing service ownership, auth, tenant, or actor boundaries?

Surface Or Workflow

The reader starts from app/web/app or app/api: login, admin, jobs, DAGs, identity resolution, marketing, geo, POA, Precon, payroll, and diagnostics. The recurring shape is UI route to client container to hooks/components to API adapter to service-owned read model or command.

Lifecycle

A surface loads a read model, renders stable state and allowed actions, collects operator intent, and calls an API route. The route validates auth and request shape, preserves tenant and actor context, and calls a service. Slow work is queued or scheduled; external providers stay behind integration services; UI code does not derive workflow state from raw analytics tables.

Child Threads

  • Route Shell Container Pattern: how frontend pages stay decomposed.
  • API Routes As Adapters: how HTTP routes stay thin.
  • Read Models: how surfaces consume stable projections.
  • Action Descriptors: how available actions are represented.
  • UI Auth And Tenant Boundaries: how access context shapes surfaces.
  • Auth And Module Access: auth implementation reference.

Implementation Boundaries

UI routes live under app/web/app; API routes under app/api; auth services under services/auth; shared read models under services/workflow/read_models; surface ownership guidance under docs/reference/operational-surface-ownership.md; route/API tests across domain suites protect request contracts and action behavior.

Tradeoffs

Pushing state into services can make a small UI change require a backend read model change. That is intentional when the state is operationally meaningful: it keeps APIs, jobs, diagnostics, and future surfaces aligned around the same capability.

Visual

The current visual is a graph neighborhood. The intended visual is a route boundary diagram from UI shell to API adapter, auth context, read model, service command, job queue, and review state.

Source Evidence

  • app/web/app
  • app/api
  • services/auth
  • services/workflow/read_models
  • docs/reference/auth.md
  • docs/reference/operational-surface-ownership.md
  • tests/precon/api
  • tests/poa
  • tests/jobs