UI API Surfaces

Summary

UI/API surfaces are the operator entry points into the platform. They are not the platform's core logic. Their job is to show operational state, collect intent, expose safe actions, and call services through routes that preserve tenant, actor, and workflow boundaries.

Reader Question

When an engineer opens a UI route or API module, how can they tell whether the surface is adapting intent correctly instead of owning business logic?

Surface Or Workflow

The entry points are app/web/app/* and app/api/*: jobs, DAGs, marketing, POA, precon, payroll, geo analysis, identity resolution, admin, and login. The reader starts from what an operator sees: a queue, run detail, case view, artifact viewer, insight surface, or repair action.

Lifecycle

A healthy surface begins with a read model. Services assemble counts, status, diagnostics, action descriptors, and artifact references. The UI presents that state without re-deriving it from raw analytics tables. When a user acts, API routes validate auth and tenant context, translate request shape into a domain command, and call a service. Slow or heavy work is enqueued rather than run inside the request.

This means a UI page should usually be a shell, a client container, hooks, and components. It should not become the owner of workflow state. API routes should be adapters. They should not speak directly to external providers or bypass service repositories.

Child Threads

  • UI API Auth Boundaries: how route shells, API adapters, auth, tenant context, read models, and action descriptors compose.
  • Route Shell Container Pattern: how Next routes, client containers, hooks, and components stay decomposed.
  • API Routes As Adapters: how routes translate HTTP requests into service capabilities.
  • Read Models: how surfaces show state without guessing.
  • Action Descriptors: how surfaces expose safe operator actions.
  • UI Auth And Tenant Boundaries: how login, module access, tenant context, and actor context shape every interactive surface.

Implementation Boundaries

Primary evidence lives under app/web/app, app/api, services/workflow/read_models, and docs/reference/auth.md. Domain threads should link back here when they need to explain a UI/API pattern instead of repeating it locally.

Tradeoffs

This approach makes simple UI changes slower when a screen needs a new service capability. The payoff is that state stays reusable: the same workflow can be shown in UI, called by API, resumed by a job, or inspected through a diagnostic surface.

Visual Notes

The current visual is a graph neighborhood. The target visual is a route map: UI route to API adapter to service/read model to job, review, or data boundary.

Source Evidence

  • app/web/app
  • app/api
  • services/workflow/read_models
  • docs/reference/auth.md