Buildstream Web Portal for Non-Agent Users

This is a specification, not a code task, and the payload names no files, tests or entry points. Start by reading the linked BR-81107 and BR-86010 specs and the open questions Q1 (multi-tenancy) and Q2 (authentication provider), which must be answered before any work. Done means a maintainer has resolved those questions and the spec is accepted and sequenced for development.

Buildstream Web Portal for Non-Agent Users

---

Summary

This specification defines a standalone web-based User Interaction Portal for the Omnia buildstream image management system. The portal provides a graphical interface for browsing, editing, and validating build catalogs, and for viewing diffs between image versions. It serves as an alternative to the AI-agent + GitLab workflow delivered in BR-81107, targeting operators and administrators who prefer a traditional click-through UI.

---

Problem Statement

BR-81107 fulfills the requirement for a "User Interaction Portal" through AI agent skills and the GitLab interface. However, not all operators will adopt AI-assisted workflows. Some sites and administrators prefer a dedicated web UI for catalog management — one that does not require familiarity with GitLab MRs, CLI tools, or AI agent invocation. Without this portal, those users lack a self-service graphical path to manage build catalogs and review image changes.

---

Value Proposition

Customer Value

• Operators get a visual, point-and-click interface for catalog browsing, creation, editing, and validation.
• Administrators can review image diffs without navigating GitLab MR interfaces.
• Lowers the barrier to entry for teams unfamiliar with Git-based workflows.

---

User Personas

• HPC Site Administrator: Manages build catalogs and image definitions for compute node functional groups. Prefers a web UI over CLI or AI tools.
• HPC Operations Engineer: Reviews image changes, triggers dry-run validations, and compares image versions before approving builds.

---

Use Cases

Use Case 1: Catalog Browsing and Editing

Actor: HPC Site Administrator
Context: The administrator needs to add a package to the gpu-compute functional group catalog.
Action: The administrator opens the web portal, navigates to the catalog, edits the package list, and saves the change.
Result: The portal validates the change against the JSON schema and submits it to the backend.

Use Case 2: Dry-Run Validation

Actor: HPC Operations Engineer
Context: A catalog change has been submitted via the portal.
Action: The engineer triggers a dry-run validation from the portal UI before the build process starts.
Result: The portal displays validation results (pass/fail, dependency issues, package availability).

Use Case 3: Image Diff Review

Actor: HPC Operations Engineer
Context: A new image has been built from an updated catalog.
Action: The engineer selects two image versions in the portal and views the package-level diff.
Result: The portal displays a clear, structured diff of all changed packages between the two versions.

---

Scope Definition

Goals (Execution Outcomes)

• Goal 1: Deliver a web-based portal for catalog browsing, creation, and editing.
• Goal 2: Integrate front-end dry-run validation that calls the buildstream backend API (BR-86010).
• Goal 3: Deliver a catalog/image diff viewer within the portal.

Non-Goals (Scope Boundaries)

• Non-Goal 1: Replacing the AI-agent + GitLab workflow (BR-81107). Both interaction models coexist.
• Non-Goal 2: Backend buildstream changes. This spec consumes existing APIs from BR-86010.
• Non-Goal 3: Build execution or artifact storage. Those remain in BR-86010.

---

Requirements

Requirement: Web Portal Catalog Management [Req 1]

The system must provide a web-based interface for browsing, creating, and editing build catalogs.

Scenario: Catalog browsing

• The portal displays all available build catalogs with their current versions, functional group assignments, and package counts.

Scenario: Catalog editing

• An administrator can add, remove, or modify packages in a catalog through the portal UI. Changes are validated against the catalog JSON schema before submission.

Requirement: Front-End Dry-Run Validation [Req 2]

The system must validate configuration changes on the front end, prior to the build process starting, whenever a new group or package is checked in.

Scenario: Dry-run trigger

• The portal provides a "Validate" action that calls the buildstream backend dry-run API and displays the result (pass/fail with details).

Scenario: Pre-build gate

• The portal prevents submission of a catalog change that fails dry-run validation, unless the operator explicitly overrides.

Requirement: Catalog Diff Viewer [Req 3]

The portal must provide visibility into image differences between catalog versions.

Scenario: Version comparison

• The portal displays a diff of all changed packages between two distinct versions of a built image when compared in the portal.

Scenario: Diff export

• The diff can be exported as a structured report (JSON or Markdown) for audit purposes.

---

Usability

• The portal must be usable by operators without Git, CLI, or AI agent experience.
• Navigation follows standard web application patterns (list → detail → edit → save).
• The diff viewer uses a familiar side-by-side or unified diff layout.

---

Reliability

• The portal operates as a stateless web frontend against the buildstream backend API (BR-86010). Availability depends on the backend service.
• The portal must gracefully handle backend unavailability with clear error messaging.

---

Security

• Must integrate with the site's existing authentication and authorization mechanisms.
• Catalog edit and build-trigger actions require appropriate role-based permissions.

---

Performance

• Catalog listing and diff rendering must complete within standard web application response times (< 3 seconds for typical catalogs).
• Dry-run validation response time depends on the backend API (BR-86010).

---

APIs

• The portal consumes the buildstream backend API defined in BR-86010.
• No new APIs are exposed by this spec; the portal is a pure frontend consumer.

---

Documentation

• User guide for portal operations (browsing, editing, validation, diff viewing).
• Administrator guide for portal deployment and configuration.

---

Dependencies

• BR-86010 (Buildstream Backend): Provides the catalog API, dry-run validation API, and image artifact storage that the portal consumes.
• BR-81107 (Buildstream Catalog Lifecycle and Authoring Methods): Delivers the AI-agent + GitLab workflow. This spec delivers the complementary web portal.

---

Risks

Risk	Category	Impact	Likelihood	Mitigation
Low adoption if AI-agent workflow proves sufficient	Business	Medium	Medium	Monitor operator usability feedback from BR-81107 before committing full development.
Backend API changes after BR-86010 release	Technical	Medium	Low	Coordinate with BR-86010 backend team on API stability guarantees.
Scope creep into backend features	Technical	Medium	Medium	Strict boundary: this spec is frontend-only, consuming existing APIs.

---

Acceptance Criteria

• AC-001: The web portal displays all available build catalogs with version, functional group, and package metadata. [Req 1]
• AC-002: An operator can create, edit, and save a build catalog through the portal UI with JSON schema validation on save. [Req 1]
• AC-003: The portal provides a dry-run validation action that calls the backend API and displays pass/fail results with detail. [Req 2]
• AC-004: The portal prevents submission of a catalog change that fails dry-run validation unless explicitly overridden. [Req 2]
• AC-005: The portal displays a package-level diff between two selected catalog or image versions. [Req 3]
• AC-006: The diff can be exported as a structured report (JSON or Markdown). [Req 3]

---

Scope & Sequencing

This spec is sequenced after BR-81107 delivery (2026-09-30). Development should begin only after usability feedback on the AI-agent + GitLab workflow is received and evaluated. May be bundled with a future release, or delivered as a standalone Omnia product enhancement.

---

Assumptions / Open Questions

Assumptions

• A1: The buildstream backend API (BR-86010) will be stable and documented by the time this spec enters development.
• A2: Usability feedback from BR-81107 will inform whether a web portal is needed or if the AI-agent + GitLab workflow is sufficient.
• A3: The portal will be deployed alongside the buildstream backend on the same infrastructure.

Open Questions

• Q1: Should the portal support multi-tenant catalog management (multiple sites/clusters), or is single-site sufficient for v1?
• Q2: What authentication provider will the portal integrate with (LDAP, SSO, GitLab OAuth)?

---