Imported from visdomtech/orca-react-sub-app-template (skills/backend-service-integration/appregistry/SKILL.md). Install upstream with npx skills add visdomtech/orca-react-sub-app-template --skill appregistry. Copyright stays with the author.

App Registry Service Integration Guide

The App Registry Service manages registered Orca application descriptors (Micro-frontends / Sub-apps), workspace-level feature enablement, and Google Cloud Build deployment pipelines.

1. Endpoint Reference Table

2. Architecture

• Route Prefix: /orcaagents/appregistry
• Auth & RBAC:
  • GET /apps: Authenticated users (returns enabled apps for caller's workspace; non-admin users see only non-adminOnly apps)
  • GET /workspace/apps, PUT /workspace/apps/{id}: Requires SYSTEM_ADMIN role
  • admin* routes: Require SYSTEM_ADMIN role (except adminGetBuild/adminListBuilds/adminGetBuildLogs which require any admin role)
• Services: appregistry.Service (CRUD + workspace enablement), appbuild.Service (Cloud Build pipeline), audit.Service (audit logging)
• Key Responsibilities:
  • CRUD for application metadata (ID, title, description, icon, badge, module federation config, approval object types)
  • Enable/disable sub-applications per tenant workspace
  • Trigger Cloud Build jobs for building and deploying bundled sub-apps to CDN

3. TypeScript Interfaces & Enums

export interface ApprovalObjectType {
  objectType: string;
  label: string;
}

export interface AppDescriptor {
  id: string;
  title: string;
  description?: string;
  iconId?: string;
  iconBg?: string;
  badge?: string;
  adminOnly: boolean;
  displayOrder: number;
  remoteUrl?: string;
  exposedModule?: string;
  currentBuildVersion?: string;
  approvalObjectTypes?: ApprovalObjectType[];
}

export interface AppWithStatus extends AppDescriptor {
  enabled: boolean;
}

export interface SetWorkspaceEnabledRequest {
  enabled: boolean;
}

export interface TriggerBuildRequest {
  fileId: string;
}

export type BuildStatus = 'QUEUED' | 'BUILDING' | 'SUCCESS' | 'FAILURE' | 'CANCELLED' | 'TIMEOUT';

export interface BuildRecord {
  buildId: string;
  jobId?: string;
  appId: string;
  fileId: string;
  status: BuildStatus;
  version: string;
  cdnDest?: string;
  errorMsg?: string;
  createdBy?: string;
  createdAt: string;        // ISO-8601
  finishedAt: string | null; // ISO-8601 or null
  logLines?: string[];       // populated on poll, not stored
}

export interface BuildLogsResponse {
  logLines: string[];
}

4. Client Functions

import { orcaFetch } from '../common';

export const appRegistryClient = {
  /** List enabled apps for current workspace navigation. */
  async listEnabledApps(): Promise<AppDescriptor[]> {
    return orcaFetch<AppDescriptor[]>('/orcaagents/appregistry/apps', { method: 'GET' });
  },

  /** List all apps (System Admin). */
  async adminListAllApps(): Promise<AppDescriptor[]> {
    return orcaFetch<AppDescriptor[]>('/orcaagents/appregistry/admin/apps', { method: 'GET' });
  },

  /** Create or overwrite an app descriptor (System Admin). */
  async adminCreateApp(app: AppDescriptor): Promise<AppDescriptor> {
    return orcaFetch<AppDescriptor>('/orcaagents/appregistry/admin/apps', {
      method: 'POST',
      body: JSON.stringify(app),
    });
  },

  /** Partially update an app descriptor (System Admin). */
  async adminUpdateApp(id: string, app: Partial<AppDescriptor>): Promise<AppDescriptor> {
    return orcaFetch<AppDescriptor>(`/orcaagents/appregistry/admin/apps/${encodeURIComponent(id)}`, {
      method: 'PATCH',
      body: JSON.stringify(app),
    });
  },

  /** Delete an app descriptor (System Admin). Returns 204. */
  async adminDeleteApp(id: string): Promise<void> {
    return orcaFetch<void>(`/orcaagents/appregistry/admin/apps/${encodeURIComponent(id)}`, { method: 'DELETE' });
  },

  /** Set app enabled for a specific workspace (System Admin). Returns 204. */
  async adminSetEnabled(id: string, workspaceId: string, enabled: boolean): Promise<void> {
    return orcaFetch<void>(
      `/orcaagents/appregistry/admin/apps/${encodeURIComponent(id)}/workspaces/${encodeURIComponent(workspaceId)}`,
      { method: 'PUT', body: JSON.stringify({ enabled }) },
    );
  },

  /** List all workspace apps with enabled toggles (System Admin). */
  async listWorkspaceApps(): Promise<AppWithStatus[]> {
    return orcaFetch<AppWithStatus[]>('/orcaagents/appregistry/workspace/apps', { method: 'GET' });
  },

  /** Toggle app enablement for current workspace (System Admin). Returns 204. */
  async setWorkspaceAppEnabled(id: string, enabled: boolean): Promise<void> {
    return orcaFetch<void>(`/orcaagents/appregistry/workspace/apps/${encodeURIComponent(id)}`, {
      method: 'PUT',
      body: JSON.stringify({ enabled }),
    });
  },

  /** Trigger a Cloud Build deployment (System Admin). Returns 202 Accepted. */
  async triggerBuild(appId: string, fileId: string): Promise<BuildRecord> {
    return orcaFetch<BuildRecord>(`/orcaagents/appregistry/admin/apps/${encodeURIComponent(appId)}/build`, {
      method: 'POST',
      body: JSON.stringify({ fileId }),
    });
  },

  /** Get build status (Admin). */
  async getBuild(appId: string, buildId: string): Promise<BuildRecord> {
    return orcaFetch<BuildRecord>(
      `/orcaagents/appregistry/admin/apps/${encodeURIComponent(appId)}/builds/${encodeURIComponent(buildId)}`,
      { method: 'GET' },
    );
  },

  /** List build records for an app (Admin). Response wraps in { builds: [...] }. */
  async listBuilds(appId: string): Promise<BuildRecord[]> {
    const res = await orcaFetch<{ builds: BuildRecord[] }>(
      `/orcaagents/appregistry/admin/apps/${encodeURIComponent(appId)}/builds`,
      { method: 'GET' },
    );
    return res.builds;
  },

  /** Fetch build logs as JSON (Admin). */
  async getBuildLogs(appId: string, buildId: string): Promise<BuildLogsResponse> {
    return orcaFetch<BuildLogsResponse>(
      `/orcaagents/appregistry/admin/apps/${encodeURIComponent(appId)}/builds/${encodeURIComponent(buildId)}/logs`,
      { method: 'GET' },
    );
  },

  /** Download build logs as plain text file attachment (Admin). */
  async downloadBuildLogs(appId: string, buildId: string): Promise<Blob> {
    const res = await fetch(
      `/orcaagents/appregistry/admin/apps/${encodeURIComponent(appId)}/builds/${encodeURIComponent(buildId)}/logs?download=true`,
      { headers: { Authorization: `Bearer ${localStorage.getItem('orca_token') || ''}` } },
    );
    if (!res.ok) throw new Error(`Download logs failed: ${res.statusText}`);
    return res.blob();
  },
};

5. Query & Path Parameters

6. SSE / Binary

• Build Logs Download: GET /builds/{buildId}/logs?download=true returns raw text as text/plain; charset=utf-8 with Content-Disposition: attachment; filename="build-{buildId}.log".
• No SSE endpoints in this service.

7. Error Scenarios