browser/openspec/changes/implement-plugin-marketplace-api-driven-ui/design.md

Context

The platform can validate and register game plugin manifests, and the frontend already has the first-party Plugin Marketplace area. The remaining gap is that the page is not yet an authoritative view over platform registry data. This change makes the marketplace page API-driven while keeping commerce concepts out of scope.

Goals / Non-Goals

Goals:

• Expose marketplace list and detail data from platform registry metadata.
• Let operators filter installed game management plugins by status, server type, keyword, and capability.
• Allow safe install/enable/disable state changes without exposing implementation internals.
• Centralize frontend API types and client methods outside page-local hidden types.
• Add tests and browser walkthrough evidence for loading, errors, filtering, install/state actions, and no-secret rendering.

Non-Goals:

• No billing, pricing, cloud host sales, provider marketplace, ratings, reviews, checkout, or subscription behavior.
• No plugin page execution, bridge transport, run-side action execution, or AI invocation implementation.
• No raw host paths, direct run sockets, raw credentials, or raw AI provider keys in responses.
• No new visual system that replaces the platform_web theme.

Decisions

Decision 1: Marketplace data is a view over installed registry metadata

Marketplace APIs will project installed plugin metadata into list/detail DTOs. The response includes identity, version, server type, status, description, pages, capabilities, permissions, and AI purposes, but not commerce data or backend internals.

Alternative considered: create a separate catalog model with publish/store metadata. Rejected because this repository is a game server management platform, and current needs are covered by installed registry data.

Decision 2: Install and state actions remain metadata-only

Install/enable/disable actions update platform plugin registry state and return the updated marketplace DTO. They do not download external packages or execute run jobs in this change.

Alternative considered: trigger package download and runtime deployment from the marketplace page. Rejected because package acquisition and run execution require separate explicit changes.

Decision 3: Frontend fallback is isolated to development

The page may keep a clearly isolated local fallback for standalone frontend development, but production flow prefers API data and shows API errors. Tests assert fallback does not leak into successful API flows.

Alternative considered: remove all fallback state immediately. Rejected because local frontend demos still need useful data when the backend is absent.

Risks / Trade-offs

• [Risk] Marketplace APIs duplicate some game plugin list/detail behavior. Mitigation: implement them as service projections over the same registry metadata.
• [Risk] Install state can be confused with package acquisition. Mitigation: name docs and DTO fields around installed/active registry state only.
• [Risk] Frontend state can drift from backend after actions. Mitigation: action methods return updated DTOs and tests cover refresh/update behavior.

Migration Plan

1. Add platform marketplace DTOs, validators, service projection, routes, and docs.
2. Update frontend API contracts and marketplace page to consume API data.
3. Add backend and frontend tests.
4. Run browser walkthrough, structure check, and strict OpenSpec validation.

Rollback before dependent changes is removal of marketplace projection routes/page API integration and this change's artifacts.

Open Questions

• Whether future plugin package publication should use signed artifacts or an internal admin upload flow.
• Whether marketplace sorting should later incorporate operational health or compatibility scores.