browser/openspec/changes/redesign-platform-web-interactions/design.md

Context

platform_web/ is the management frontend for a game server management platform. The required first-party areas are home, server management, plugin marketplace, user management, and AI provider management. The current interaction model does not sufficiently distinguish platform administrators from server owners/administrators, and daily operations lack consistent feedback, traceability, and safe confirmation paths.

The target experience is a visually expressive anime/game operations workspace: themeable backgrounds, colorful status blocks, and a playful visual tone inspired by magical-girl and virtual-idol interfaces. The shared visual system must read as crystal moonlight rather than opaque pastel cards: high transparency, icy rim light, diamond-like borders, glossy jelly controls, built-in magical desktop presets, a unified theme-aware magical ultimate-effect layer, and visible user/custom backgrounds through safe readability overlays. This must use original assets or user-provided backgrounds rather than copyrighted character art. It must not weaken operational clarity. Server status, logs, configuration diffs, plugin actions, LLM output, and errors must remain readable and debuggable.

Goals / Non-Goals

Goals:

• Route users to role-appropriate default workspaces after login.
• Support the current identity flows: registration, login, platform-admin user creation, user management, and current-user profile editing.
• Give platform administrators a first-screen platform health overview.
• Give server owners and server administrators a first-screen server list with actionable server status.
• Consolidate day-to-day server work inside the server detail workspace: overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history.
• Provide consistent empty, loading, error, success, failure, and diagnostic states across platform_web.
• Make every user-triggered operation visible and traceable through an operation/job ID.
• Preserve AI provider and run-channel safety constraints.
• Establish a themeable anime/game visual system that supports user-uploaded backgrounds and per-user visual preferences while keeping text and controls readable.

Non-Goals:

• No billing, cloud host sales, cloud provider workflows, SaaS marketplace features, or unrelated commercial flows.
• No raw AI keys, raw credentials, host paths, or direct sockets exposed to platform_web or plugin pages.
• No implementation of new game plugin business logic beyond rendering and invoking declared per-server plugin controls.
• No silent LLM writes to server configuration.
• No direct signup path to platform administrator privileges without platform-admin approval or bootstrap policy.

Decisions

Role-specific workspace routing

Users will enter a workspace based on their highest relevant role for the current session. Platform administrators land on the platform overview. Server owners and server administrators land on the server list and do not see platform overview navigation.

Alternative considered: a single universal dashboard for all roles. This was rejected because it leaks irrelevant platform concepts to server-only users and makes the first screen less useful for the daily workflows.

Navigation is capability-scoped

The side navigation and mobile bottom navigation will be generated from the user's role/capability set. Platform administrators can access platform overview, server management, plugin marketplace, user management, AI provider management, and system maintenance. Server owners and server administrators can access their server list, server detail workspaces, and allowed plugin/config/log operations only.

Alternative considered: render all navigation and disable unauthorized items. This was rejected because hidden platform areas are cleaner and reduce confusion for server administrators.

Identity and profile are first-class console flows

The frontend will expose registration and login as unauthenticated flows, user creation and user management as platform-administrator flows, and profile/contact/theme editing from the current user's avatar menu. Profile fields include display name, avatar, phone, QQ, and other bounded contact fields. Theme preferences include uploaded desktop/background imagery and visual theme settings, stored per user when authenticated and allowed to fall back to local storage before the profile API exists.

Alternative considered: keeping theme upload only as a shell control and contact fields only in user management. This was rejected because users expect personal settings to live behind their own avatar, while platform administrators still need centralized user management.

Server detail is the daily operations hub

Each server detail page will contain tabs or sections for overview, logs, configuration, plugin controls, LLM configuration assistance, and operation history. Plugin controls are grouped by plugin within the server detail page. The plugin marketplace remains responsible for plugin discovery, install/update status, and plugin documentation.

Alternative considered: a global plugin control console where users select plugins first and servers second. This was rejected because daily operators think in terms of "this server has a problem" or "this server needs an action" rather than starting from a plugin catalog.

Per-server plugin isolation

The UI model will treat a plugin installation/control surface as scoped to a server instance. Multiple servers can use the same plugin, but each server displays independent plugin state, configuration, actions, and operation history.

Alternative considered: shared plugin state shown globally in the marketplace. This was rejected because it obscures which server will be affected by a control action and can lead to unsafe cross-server assumptions.

Operation/job feedback as a shared interaction pattern

Every user-triggered action that reaches platform/run/plugin/LLM systems will create or reference a visible operation/job. Buttons transition through pending/loading/success/failure states, and failures include error reason, operation/job ID, and retry or diagnostic actions where available.

For complex actions, the frontend should present one business operation to the user, even if the backend performs multiple steps. The operation detail can expose the operation ID, target, requester, status, timestamps, and diagnostics. Frontend code must avoid wiring one button directly to several unrelated API calls whose combined outcome cannot be traced.

Alternative considered: local toast-only feedback. This was rejected because transient toasts do not support debugging, audit, or long-running run-side operations.

LLM-assisted configuration is review-first

LLM configuration assistance will produce recommendations or a reviewable diff. The user must confirm the diff before platform dispatches any run-side write job. Plugin pages and platform_web must not receive raw AI provider keys.

Alternative considered: allowing LLM suggestions to write directly after prompt submission. This was rejected because server configuration changes require operator review and auditability.

Visual theme with readability constraints

The frontend will support an anime/game visual direction with user-uploaded background imagery, built-in magical desktop presets, saturated color blocks, crystalline highlights, and expressive accents suitable for a cute game operations console. The default theme system will include multiple magical-girl palettes built from strawberry pink, lavender purple, mint green, milk yellow, icy blue, white highlights, and bright gold accents. The shared style language is crystal moonlight: panels remain transparent enough to reveal the background, cards use diamond-like borders and white/icy-blue rim lights, buttons look like glossy jelly candy, and decorative motifs use original ribbon and magic-circle motifs plus a shell-level canvas for theme-specific magical ultimate effects. Built-in backgrounds should feel like original magical desktops such as moon sigils, candy starlight, ribbon sweeps, mint crystal facets, and aqua aurora, while uploaded user imagery takes precedence when present. Operational surfaces such as logs, configuration diffs, errors, and forms must use readable contrast layers and stable layout constraints. Status must be represented with text/icons as well as color.

Alternative considered: making the whole UI a decorative landing-page style. This was rejected because the product is a repeated-use operations tool, not a marketing site.

Responsive behavior favors task focus

Desktop uses role-scoped side navigation and multi-column dashboards/lists. Narrow screens use compact top context, single-column cards, bottom navigation where appropriate, drawers for filters/details, and collapsible plugin groups.

Alternative considered: shrinking the desktop layout uniformly. This was rejected because dense operational panels become unreadable and hard to use on narrow screens.

Risks / Trade-offs

• [Risk] Rich backgrounds reduce readability. -> Mitigation: use contrast overlays, fixed panel surfaces, and visual QA on desktop and mobile.
• [Risk] Anime-style visuals drift into copyrighted character references. -> Mitigation: use original UI motifs, abstract color, user-uploaded backgrounds, and avoid bundling recognizable third-party character assets.
• [Risk] Role-based navigation hides a needed action from hybrid users. -> Mitigation: define deterministic role precedence and allow explicit workspace switching only for users with multiple allowed workspaces.
• [Risk] Registration can create unauthorized access if role assignment is too broad. -> Mitigation: new self-registered users default to a pending or server-scoped role until a platform administrator approves or assigns capabilities.
• [Risk] Operation/job tracking requires API support that may not exist for all actions. -> Mitigation: inventory existing APIs during implementation and add scoped platform contracts where necessary.
• [Risk] Plugin control schemas may vary widely. -> Mitigation: render plugin controls from explicit plugin/page contracts and keep unsupported controls in a clear unavailable state.
• [Risk] LLM diff review can slow expert operators. -> Mitigation: keep diff confirmation efficient, but do not bypass review for write jobs.
• [Risk] Mobile cannot expose all desktop controls at once. -> Mitigation: prioritize server status, search, logs, and common actions; move advanced filters and diagnostics into drawers/details.

Migration Plan

1. Add or adapt platform_web route contracts for role-aware entry and navigation.
2. Add identity/profile contracts for registration, login, current-user loading, user creation, user management, profile contact fields, avatar settings, and per-user theme preferences.
3. Implement shared layout/theme primitives and state components before page rewrites.
4. Replace the platform administrator landing page with the platform overview.
5. Replace the server-owner/admin landing page with the server list.
6. Rework server detail into the daily operations hub with logs, config, plugin controls, LLM assistance, and operation history.
7. Integrate operation/job feedback patterns into all actionable controls touched by the redesign.
8. Verify responsive behavior and browser walkthroughs before marking UI acceptance complete.

Rollback is page-level: retain route boundaries so individual redesigned pages can be disabled or reverted if a critical interaction blocks operators.

Open Questions

• Should hybrid users who are both platform administrators and server administrators get a visible workspace switcher, or should platform overview always be the only default entry with server access through navigation?
• Which existing backend operation/job APIs can be reused, and which operations need new platform contracts?