API Routes and Engines

Reference for how request handling, orchestration, numerical execution, and export-oriented metadata fit together in the current release.

This page describes the current boundary between product-facing routes and the engines they coordinate.

High-level split

In the current release, API routes are responsible for request handling, authorization, orchestration, and packaging of user-facing responses. Numerical engines are responsible for the computational work itself.

In practice, that means:

  • routes decide which workflow surface is being requested
  • routes validate inputs and shape outputs for the product contract
  • engines perform the statistical or rendering-related computation
  • audit and export surfaces package the result into reusable metadata

Why this split exists

This separation keeps the user-facing contract stable even when the underlying computation layer evolves.

It also allows the product to:

  • keep HTTP and product concerns separate from numerical implementation details
  • version computational behavior explicitly
  • retain audit metadata about how an artifact was generated
  • expose exports and reproducibility surfaces without forcing UI code to know the internals of the computation layer

Route responsibilities

Product-facing routes should be read as the contract boundary. They define what the client can request and what metadata or exports are made available in response.

Typical route-layer responsibilities include:

  • authentication and access control
  • request validation
  • choosing the correct downstream engine path
  • shaping the response into a stable product-facing format
  • exposing generation metadata or exportable artifacts through authenticated endpoints

Engine responsibilities

Engine responsibilities begin after the route boundary has already determined the requested task and validated the request context.

Typical engine-layer responsibilities include:

  • numerical computation
  • statistical default selection and fallback logic
  • figure generation or related artifact computation
  • internal intermediate state needed for auditability or reproducibility

For the current split between JS orchestration and Python numerical execution, see JS vs Python Execution Model.

Audit-oriented surfaces

Some route surfaces exist primarily to expose generation context rather than to re-run the underlying computation directly.

Examples of route-facing outputs include:

  • audit-oriented metadata about how a figure or artifact was generated
  • export payloads that package result details for downstream use
  • reproducibility-oriented metadata such as version or snapshot context

Use the following pages for output-oriented details:

Important interpretation rule

The existence of an engine capability does not automatically mean there is a matching public route contract for every nearby workflow.

Likewise, a route can expose a narrow product surface without implying that the underlying engine supports every adjacent methodological variation.

When in doubt, read route behavior as the public contract and engine behavior as the implementation policy behind that contract.