Aja Distributed Processing

Purpose#

Admin lane console wired to the real @aja/distributed-workers autoscaler via /v1/admin/aja/distributed-processing. Its single "Autoscaler Operations Lane" sizes the worker pool needed to clear a queue by a deadline (queue depth + avg task time + target completion → optimal workers, clamped to policy bounds) and scores scaling efficiency from actual throughput vs. theoretical.

Entry points#

• Direct URL — /studio/aja/distributed-processing (signed-in + studio entitlement)
• Sibling quick-actions from this page — Batch Operations, Back to Studio

Layout regions#

page.tsx mounts ShellLayout with active="studio" and renders three panels.

• Workspace panel (data-aja-distributed-processing-workspace):
  • <h1> "Aja Distributed Processing Workspace" (via WorkspaceHeading)
  • <p data-aja-distributed-processing-summary> — "Dedicated Distributed Processing route with dense expert-mode controls, progressive disclosure, and canonical route map. The operations lane sizes the worker pool and scores scaling efficiency on the real autoscaler."
  • <h2 data-aja-dp-lane-heading> "Autoscaler Operations Lane" wrapping the plan + efficiency forms (data-aja-dp-engine-summary from the catalog)
• Route Map panel (data-aja-distributed-processing-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_DISTRIBUTED_PROCESSING_ROUTE_MAP entry (5 entries)
• Quick actions panel: .quickAction <Link>s — see Interactions

States#

• Loading — data-aja-dp-loading "Loading autoscaler…"
• Unauthorized — on 401/403, data-aja-dp-unauthorized ("Access restricted." + reason, default "Aja workspace scope required to plan distributed processing.")
• Error — non-OK / malformed / unreachable → data-aja-dp-error
• Ready (forms) — catalog present: plan form + efficiency form
• Plan result — data-aja-dp-plan-result "optimal workers: N (range min–max)" (with "· clamped to max" when clampedToMax)
• Efficiency result — data-aja-dp-eff-result "scaling efficiency: x (n% of theoretical)"
• Validation errors — data-aja-dp-plan-error / data-aja-dp-eff-error (e.g. "Provide a non-negative integer queue depth and positive task / deadline times.")

Interactions#

Plan form (data-aja-dp-plan-form)#

• Queue depth — input data-aja-dp-queue (number)
• Avg task (ms) — input data-aja-dp-taskms (number)
• Deadline (ms) — input data-aja-dp-deadline (number)
• Size worker pool — button data-aja-dp-plan-submit; posts to /v1/admin/aja/distributed-processing/plan-workers with queue depth, average task duration, and target completion fields

Efficiency form (data-aja-dp-eff-form)#

• Actual throughput (/min) — input data-aja-dp-throughput
• Worker count — input data-aja-dp-workers
• Avg task (ms) — input data-aja-dp-eff-taskms
• Score efficiency — button data-aja-dp-eff-submit; posts to /v1/admin/aja/distributed-processing/efficiency with { actualThroughput, workerCount, avgTaskDurationMs }

Route Map panel (data-aja-distributed-processing-route-map)#

Non-interactive <article> blocks from STUDIO_AJA_DISTRIBUTED_PROCESSING_ROUTE_MAP (5 entries): /studio/aja/distributed-processing plus …/scenes/[sceneId], …/exports/[exportId], …/revisions/[revisionId], …/governance/[policyId].

Quick actions panel#

• Open Aja Batch Operations workspace → /studio/aja/batch-operations
• Back to Studio workspace index → /studio

E2E coverage#

• apps/oshun/web/e2e/studio-aja-pipeline-control-lane-consoles.spec.ts covers signed-in shell render, ready plan and efficiency forms, client guards with no POST for negative queue depth and fractional worker count, real BFF worker-plan output (optimal workers: 10, range 1–10, clamped to max), real scaling-efficiency output (0.25 / 25% of theoretical), route-map count, exact quick-action hrefs, 44 px submit targets, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates.

Data & contracts#

• Reads: GET /v1/admin/aja/distributed-processing (catalog: summary, defaultPolicy) on mount via buildBffAuthHeaders(), cache: 'no-store'
• Writes: POST …/plan-workers → { result: WorkerPlan }; POST …/efficiency → { result: { efficiency } }
• Realtime: none
• Caching: client fetch on mount (no-store); SSR shell only
• Auth: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); the route is signed-in + studio (proxy gate)

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaDistributedProcessingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaDistributedProcessingRouteMap.ts
• Embedded by aggregator: apps/oshun/web/src/components/studio/StudioAjaMotionProcessingWorkspace.tsx (Distributed Processing Lane)
• Sibling from quick-actions: /studio/aja/batch-operations

Known downstream boundaries#

• Route-map sub-routes (scenes/exports/revisions/governance) are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.
• The route remains governed by the shared signed-in + studio entitlement proxy gate for /studio/aja/*.