Studio Aja · Search and Discovery

Purpose#

Admin lane console for the real field-weighted relevance ranker. The operator supplies a reference-asset catalog (JSON array), a query, and an optional required-tag filter; the lane ranks the catalog for the query (title weight 3 > tag 2 > description 1), filters to the required tag when given, drops zero-score items, and reads back the matched/total counts and the scored results with their matched fields.

Entry points#

• Direct URL / bookmark — /studio/aja/search-and-discovery; metadata canonical to this path
• Studio nav — Domain-bridge studios section of /studio
• Sibling quick-actions on this page: Reference Video Library, Back to Studio (no breadcrumb panel on this route)
• Operator surfacing — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace (<StudioAjaSearchAndDiscoveryWorkspace />, archetype: LEAF):
  • <h1> (WorkspaceHeading) "Aja Search and Discovery Workspace"
  • Summary <p data-aja-search-and-discovery-summary> — discovery lane runs a real field-weighted relevance ranker (title 3 > tag 2 > description 1)
  • Relevance Ranking Lane (<h2 data-aja-sd-lane-heading> "Relevance Ranking Lane") — the live search form
• Route Map panel (data-aja-search-and-discovery-route-map): <h2>Route Map</h2> listing 5 entries from STUDIO_AJA_SEARCH_AND_DISCOVERY_ROUTE_MAP (primary, scenes, exports, revisions, governance)
• Quick-action panel: two Link.quickAction anchors — Reference Video Library, Back to Studio workspace index

States#

• Loading — GETs the ranker catalog on mount; renders <p data-aja-sd-loading> "Loading relevance ranker…"
• Unauthorized — 401/403 renders data-aja-sd-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to rank the catalog.")
• Error — non-OK / malformed / unreachable renders data-aja-sd-error ("Could not load the relevance ranker." + reason)
• Ready (form) — success renders data-aja-sd-engine-summary, data-aja-sd-weights (field weights), and the data-aja-sd-form
• Result — a successful POST renders data-aja-sd-result with data-aja-sd-headline (matched/total) and a data-aja-sd-results-list of data-aja-sd-result-row (id · title · score · matched fields)
• Validation / search error — invalid/non-array items JSON or POST failure renders data-aja-sd-search-error
• Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

Relevance Ranking Lane (data-aja-sd-form)#

• Catalog items (data-aja-sd-items, textarea, aria-label "catalog items json", JSON array)
• Query (data-aja-sd-query, input, aria-label "query")
• Required tag (data-aja-sd-tag, input, aria-label "required tag", optional)
• "Rank catalog" (data-aja-sd-submit, submit) — fires POST /v1/admin/aja/search-and-discovery/search with { items, query, tag? }

Route Map panel#

• Route entries (5 × <article>) — non-interactive path+purpose

Quick-action panel#

• "Open Aja Reference Video Library workspace" → /studio/aja/reference-video-library
• "Back to Studio workspace index" → /studio

Data & contracts#

• Reads: GET /v1/admin/aja/search-and-discovery on mount — catalog { summary, fieldWeights }
• Writes: POST /v1/admin/aja/search-and-discovery/search — { items, query, tag? } → { result } (total, matched, results[])
• Realtime: none
• Caching: client fetch on mount with cache: 'no-store' and buildBffAuthHeaders(); SSR shell only
• Auth/role check: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); route behind the signed-in + studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-reference-video-library.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaSearchAndDiscoveryWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaSearchAndDiscoveryRouteMap.ts

Open questions / known gaps#

• Route-map sub-routes are advertised but have no page.tsx in V1