|
| 1 | +# PRD: AI Catalog Foundation |
| 2 | + |
| 3 | +**Product:** Boost — Agentic Developer Portal for Red Hat Developer Hub |
| 4 | +**Status:** Partially implemented (scaffold delivered 2026-06-30; gallery/content deferred) |
| 5 | +**Date:** 2026-06-30 |
| 6 | +**Updated:** 2026-06-30 — reverse-engineered from implementation commits `0fb77e76..5fe7580c` |
| 7 | +**Priority:** P0 (prerequisite for all frontend work) |
| 8 | +**Provenance:** Reverse-engineered from shipped implementation. See `specifications/boost-context.md` for project context. |
| 9 | +**Related PRDs:** [Agent Creation & Discovery](agent-creation-discovery.md) (future gallery content), [Platform Operations & Deployment](platform-operations-deployment.md) (deployment paths, UC-15) |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Why |
| 14 | + |
| 15 | +Developers need a runnable Boost frontend before building agent gallery, chat, or admin UI. The AI Catalog route is the designated primary navigation entry point for discovering AI agents and related catalog entities. |
| 16 | + |
| 17 | +This PRD captures the bootstrap intent established by the first frontend implementation: create the Backstage New Frontend System (NFS) plugin, wire it into a full local dev shell, and reserve `/ai-catalog` as the home for future discovery UX. The page scaffold is intentionally empty — it establishes routing, navigation, and development infrastructure, not the full agent gallery described in UC-4 and UC-9. |
| 18 | + |
| 19 | +## What This Product Does |
| 20 | + |
| 21 | +Boost ships `@red-hat-developer-hub/backstage-plugin-boost` as a Backstage NFS frontend plugin. The plugin registers a lazy-loaded `/ai-catalog` page with a sidebar nav item and icon. A full-stack local dev shell (`packages/app` + `packages/backend`) wires all existing Boost backend plugins for end-to-end testing. Local and production app-config templates provide the `boost.*` configuration namespace. |
| 22 | + |
| 23 | +The current AI Catalog page renders a header and an empty content container — a placeholder for agent gallery, search, filter, and preview panel functionality defined in the Agent Creation & Discovery PRD. |
| 24 | + |
| 25 | +## Who It's For |
| 26 | + |
| 27 | +### Boost Developer |
| 28 | + |
| 29 | +Iterates on frontend features against a real app and backend. Uses `yarn start` for full-stack development or `yarn dev` for isolated plugin iteration. |
| 30 | + |
| 31 | +### Plugin Consumer |
| 32 | + |
| 33 | +References this PRD when registering the boost plugin in a custom NFS app or RHDH dynamic plugin deployment. |
| 34 | + |
| 35 | +## Boundaries |
| 36 | + |
| 37 | +### In Scope |
| 38 | + |
| 39 | +- NFS frontend plugin package structure and extension patterns (`PageBlueprint`, `createRouteRef`, lazy loader) |
| 40 | +- `/ai-catalog` routable page extension with title and icon |
| 41 | +- Dev shell (`packages/app`, `packages/backend`) with boost plugin registration |
| 42 | +- Local dev configuration (guest auth, allow-all permissions — explicitly dev-only) |
| 43 | +- Production config overlay skeleton (env vars, PostgreSQL, full security mode) |
| 44 | +- Plugin family metadata (`pluginPackages`) |
| 45 | +- Basic extension and app smoke tests |
| 46 | + |
| 47 | +### Out of Scope |
| 48 | + |
| 49 | +- Agent gallery UI (search, filter, tabs, preview panel) — see [Agent Creation & Discovery PRD](agent-creation-discovery.md) UC-4, UC-9 |
| 50 | +- Chat UI, admin panels, capability-gated rendering — see [AI Chat & Interaction PRD](ai-chat-interaction-experience.md) and [Platform Operations PRD](platform-operations-deployment.md) |
| 51 | +- Fine-grained RBAC — see [Security & Governance PRD](security-safety-governance.md) |
| 52 | +- Real catalog entity rendering on the AI Catalog page |
| 53 | +- E2E tests for the full app flow |
| 54 | +- Production-ready Docker image (Dockerfile ships with dev-config warning) |
| 55 | + |
| 56 | +### UX/UXD Integration |
| 57 | + |
| 58 | +The scaffold page uses Backstage `@backstage/ui` primitives only. Full AI Catalog UX (agent cards, gallery layout, preview panel) requires UX/UXD mockups per the Agent Creation & Discovery PRD before implementation replaces the empty container. |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## Capabilities |
| 63 | + |
| 64 | +### 1. Boost Frontend Plugin on NFS |
| 65 | + |
| 66 | +**Goal:** Establish the boost frontend plugin using Backstage's New Frontend System as the foundation for all future UI. |
| 67 | + |
| 68 | +**Package:** |
| 69 | + |
| 70 | +| Field | Value | |
| 71 | +| -------------- | ----------------------------------------------- | |
| 72 | +| npm name | `@red-hat-developer-hub/backstage-plugin-boost` | |
| 73 | +| Backstage role | `frontend-plugin` | |
| 74 | +| pluginId | `boost` | |
| 75 | +| Location | `workspaces/boost/plugins/boost/` | |
| 76 | + |
| 77 | +**How it works:** |
| 78 | + |
| 79 | +- Plugin instance created via `createFrontendPlugin({ pluginId: 'boost', extensions: [boostPage], routes: { root: rootRouteRef } })` |
| 80 | +- Page extension defined via `PageBlueprint.make` with lazy loader |
| 81 | +- Default export is the plugin instance (`export { boostPlugin as default }`) |
| 82 | +- Route ref created via `createRouteRef()` in `routes.ts` |
| 83 | +- Plugin family metadata lists six boost npm packages in `backstage.pluginPackages` |
| 84 | + |
| 85 | +**Plugin family packages (`pluginPackages`):** |
| 86 | + |
| 87 | +- `@red-hat-developer-hub/backstage-plugin-boost` |
| 88 | +- `@red-hat-developer-hub/backstage-plugin-boost-backend` |
| 89 | +- `@red-hat-developer-hub/backstage-plugin-boost-common` |
| 90 | +- `@red-hat-developer-hub/backstage-plugin-boost-node` |
| 91 | +- `@red-hat-developer-hub/backstage-plugin-boost-responses-api-toolkit` |
| 92 | +- `@red-hat-developer-hub/backstage-plugin-boost-toolscope` |
| 93 | + |
| 94 | +**Acceptance criteria:** |
| 95 | + |
| 96 | +- Plugin builds and exports as a valid NFS frontend plugin |
| 97 | +- Default export resolves to the plugin instance |
| 98 | +- All six family packages listed in `pluginPackages` |
| 99 | + |
| 100 | +### 2. AI Catalog Routable Page |
| 101 | + |
| 102 | +**Goal:** Register `/ai-catalog` as the primary Boost navigation entry point with lazy-loaded page content. |
| 103 | + |
| 104 | +**How it works:** |
| 105 | + |
| 106 | +- `PageBlueprint` params: `path: '/ai-catalog'`, `title: 'AI Catalog'`, `icon: <AiCatalogIcon />` |
| 107 | +- Page component loaded via `import('./components/AiCatalogPage').then(m => <m.AiCatalogPage />)` |
| 108 | +- `AiCatalogIcon` wraps MUI `StorefrontIcon` as a placeholder sidebar icon |
| 109 | +- Scaffold page renders `@backstage/ui` `Header` with title "AI Catalog" and an empty `Container` |
| 110 | + |
| 111 | +**Acceptance criteria:** |
| 112 | + |
| 113 | +- Navigating to `/ai-catalog` renders the AI Catalog page |
| 114 | +- Sidebar shows "AI Catalog" with the plugin icon |
| 115 | +- Page component is lazy-loaded (not bundled in the main plugin entry) |
| 116 | +- Unit test asserts extension route path is `/ai-catalog` and title is `AI Catalog` |
| 117 | + |
| 118 | +### 3. Local Dev Shell |
| 119 | + |
| 120 | +**Goal:** Provide a full Backstage app and backend for end-to-end Boost development without requiring an external RHDH instance. |
| 121 | + |
| 122 | +**Frontend (`packages/app`):** |
| 123 | + |
| 124 | +- NFS app created via `createApp({ features: [...] })` |
| 125 | +- Registered features: RHDH theme module, custom nav module, guest sign-in module, catalog plugin, boost plugin |
| 126 | +- Nav sidebar surfaces `page:catalog` (Software Catalog) and `page:boost` (AI Catalog) |
| 127 | +- Catalog index page mounted at `/` via app extension config |
| 128 | + |
| 129 | +**Backend (`packages/backend`):** |
| 130 | + |
| 131 | +- Standard Backstage plugins: app, proxy, scaffolder, techdocs, auth (guest), catalog, permission (allow-all policy), search, kubernetes, notifications, signals, mcp-actions |
| 132 | +- All Boost backend plugins: `boost-backend`, `boostAiProviderServiceFactory`, `boost-backend-module-llamastack`, `boost-backend-module-kagenti`, `llamastack-entity-provider`, `kagenti-entity-provider` |
| 133 | + |
| 134 | +**Acceptance criteria:** |
| 135 | + |
| 136 | +- `yarn start` from workspace root launches frontend and backend |
| 137 | +- Boost plugin appears in sidebar alongside Software Catalog |
| 138 | +- Backend registers all six Boost backend packages |
| 139 | +- App smoke test renders without error |
| 140 | + |
| 141 | +### 4. Configuration |
| 142 | + |
| 143 | +**Goal:** Supply local and production configuration templates for the dev shell and boost namespace. |
| 144 | + |
| 145 | +**Local dev (`app-config.yaml`):** |
| 146 | + |
| 147 | +| Key | Value / purpose | |
| 148 | +| ----------------------- | ------------------------------------------- | |
| 149 | +| `app.title` | `Boost Dev` | |
| 150 | +| `backend.database` | `better-sqlite3`, in-memory | |
| 151 | +| `auth.providers.guest` | Guest provider with auto sign-in (dev only) | |
| 152 | +| `permission.enabled` | `true` with allow-all policy module | |
| 153 | +| `boost.security.mode` | `development-only-no-auth` | |
| 154 | +| `boost.model` | Local Llama Stack endpoint | |
| 155 | +| `boost.providers` | Llama Stack and Kagenti base URLs | |
| 156 | +| `boost.entityProviders` | Matching entity provider base URLs | |
| 157 | + |
| 158 | +**Production overlay (`app-config.production.yaml`):** |
| 159 | + |
| 160 | +| Key | Value / purpose | |
| 161 | +| --------------------- | ------------------------------------------------------ | |
| 162 | +| `backend.database` | PostgreSQL via env vars | |
| 163 | +| `backend.auth.keys` | Service-to-service auth secret | |
| 164 | +| `auth.environment` | `production` | |
| 165 | +| `boost.security.mode` | `full` | |
| 166 | +| `boost.*` endpoints | Env-var placeholders (`${BOOST_MODEL_BASE_URL}`, etc.) | |
| 167 | + |
| 168 | +**Acceptance criteria:** |
| 169 | + |
| 170 | +- Local config includes comments marking dev-only settings (guest auth, allow-all permissions, in-memory database) |
| 171 | +- Production overlay overrides database, auth, and security mode |
| 172 | +- `boost.*` namespace present in both configs |
| 173 | + |
| 174 | +### 5. Developer Workflows |
| 175 | + |
| 176 | +**Goal:** Support full-stack and isolated plugin development with a validation pipeline. |
| 177 | + |
| 178 | +| Command | Purpose | |
| 179 | +| --------------- | ------------------------------------------------------------------------------------------ | |
| 180 | +| `yarn start` | Full app (packages/app + packages/backend); navigate to `http://localhost:3000/ai-catalog` | |
| 181 | +| `yarn dev` | Parallel isolated frontend and backend plugin dev servers | |
| 182 | +| `yarn chores` | Format, lint, typecheck, API reports, OpenSpec validate, tests | |
| 183 | +| `yarn test:all` | Prettier, lint, tests with coverage | |
| 184 | + |
| 185 | +**Isolated plugin dev (`plugins/boost/dev/index.tsx`):** |
| 186 | + |
| 187 | +- Uses `createDevApp({ features: [plugin] })` |
| 188 | +- Redirects `/` to `/ai-catalog` on load |
| 189 | + |
| 190 | +**Acceptance criteria:** |
| 191 | + |
| 192 | +- Both `yarn start` and isolated plugin dev land on `/ai-catalog` |
| 193 | +- `yarn dev` starts boost frontend and boost-backend plugin servers in parallel |
| 194 | + |
| 195 | +### 6. Verification |
| 196 | + |
| 197 | +**Goal:** Ensure the plugin extension metadata and app integration are testable. |
| 198 | + |
| 199 | +**Plugin tests (`plugins/boost/src/plugin.test.ts`):** |
| 200 | + |
| 201 | +- Plugin instance is defined |
| 202 | +- `boostPage` extension exposes route path `/ai-catalog` and title `AI Catalog` |
| 203 | + |
| 204 | +**App tests (`packages/app/src/App.test.tsx`):** |
| 205 | + |
| 206 | +- App renders without error given minimal test config |
| 207 | + |
| 208 | +**Acceptance criteria:** |
| 209 | + |
| 210 | +- Plugin unit tests pass |
| 211 | +- App smoke test passes |
| 212 | + |
| 213 | +--- |
| 214 | + |
| 215 | +## Architecture Context |
| 216 | + |
| 217 | +**NFS over legacy:** The boost frontend plugin uses `@backstage/frontend-plugin-api` blueprints (`PageBlueprint`, `createFrontendPlugin`), not legacy `createPlugin` / routable extensions. Future pages (chat, admin) should follow the same pattern with lazy loading at extension boundaries. |
| 218 | + |
| 219 | +**Naming:** The frontend package is `boost` (directory: `plugins/boost/`), not `boost-frontend`. npm scope is `@red-hat-developer-hub/backstage-plugin-boost`. |
| 220 | + |
| 221 | +**Relationship to agent discovery:** `/ai-catalog` is the future home for UC-4 (Browse and Select an Agent) and UC-9 (Discover Agents in the Gallery) gallery UX. The current scaffold intentionally leaves the content container empty. |
| 222 | + |
| 223 | +**Backstage version:** Workspace aligned to Backstage 1.52.0 (see `backstage.json`). |
| 224 | + |
| 225 | +**Dev shell vs. production deployment:** The dev shell in `packages/` is for local development only. RHDH production deployment uses dynamic plugins (see `dynamic-plugins-filesystem-reference.yaml` and `dynamic-plugins-image-reference.yaml`). The backend Dockerfile includes a warning that it bundles dev-config and is not production-ready without overrides. |
| 226 | + |
| 227 | +**Lazy loading convention:** All heavy UI should be loaded via dynamic `import()` at the PageBlueprint loader boundary. This establishes the pattern for future chat, admin, and gallery components. |
| 228 | + |
| 229 | +--- |
| 230 | + |
| 231 | +## Future Evolution |
| 232 | + |
| 233 | +The empty `Container` in `AiCatalogPage` will be replaced incrementally: |
| 234 | + |
| 235 | +1. **Agent gallery content** — agent cards, search, filter, tabs, preview panel per [Agent Creation & Discovery PRD](agent-creation-discovery.md) |
| 236 | +2. **Catalog entity integration** — render agents, models, tools, and MCP servers from Backstage catalog entities emitted by entity providers |
| 237 | +3. **Additional routes** — chat experience and admin panels as additional `PageBlueprint` extensions or nested routes within the boost plugin |
| 238 | + |
| 239 | +--- |
| 240 | + |
| 241 | +## Traceability |
| 242 | + |
| 243 | +| Capability | Use Case | Priority | Status | |
| 244 | +| ----------------------- | ----------------------------- | -------- | ----------- | |
| 245 | +| AI Catalog route + nav | UC-4, UC-9 (entry point only) | P0 | Scaffold | |
| 246 | +| Dev shell | UC-15 (local dev path) | P0 | Delivered | |
| 247 | +| Plugin registration | UC-15 (static plugin path) | P0 | Delivered | |
| 248 | +| NFS frontend plugin | (foundation) | P0 | Delivered | |
| 249 | +| Configuration templates | UC-15 | P0 | Delivered | |
| 250 | +| Developer workflows | (foundation) | P0 | Delivered | |
| 251 | +| Gallery content | UC-4, UC-9 | P1 | Not started | |
| 252 | +| Chat UI | UC-1 | P0 | Not started | |
| 253 | +| Admin panels | UC-17, UC-21 | P0 | Not started | |
| 254 | + |
| 255 | +--- |
| 256 | + |
| 257 | +## Customer Context |
| 258 | + |
| 259 | +This foundation enables the specification-driven development workflow defined in `AGENTS.md`: developers can now implement features against a runnable app, verify backend integration locally, and iterate on the AI Catalog page as agent discovery capabilities are built out per the Agent Creation & Discovery PRD. |
0 commit comments