Status: Proposed. This is an analysis and design direction, not an implementation commitment.
Improve the configuration dashboard’s usability, consistency, and maintainability without weakening its safety model or replacing its deliberately small, dependency-light browser application.
The admin web service is a separate, BC-disconnected application. It has a map-centred configuration workspace, focused administration tasks, searchable record lists and selectors, configuration-health and impact reviews, dedicated MOTD and appearance editors, and administrator-only recovery and account views. Changes remain drafts until reviewed and explicitly saved. The service distinguishes stored configuration from live BC state.
The client already has important usability and safety features: unsaved-change warnings, conflict recovery, keyboard map editing, responsive layouts, and accessible status and control labels. The proposal builds on those foundations; it does not assume the dashboard needs a wholesale redesign.
The current implementation also has clear opportunities for incremental improvement. Workspace search is scoped to the selected category; workspace startup requests the workspace, appearance catalog, and itemsets in sequence; browser request handling is implemented in several page modules; and the workspace client and server-side workspace module have grown to approximately 3,000 and 3,500 lines respectively. These observations motivate the work below, but do not by themselves establish a performance problem: measure before optimizing.
Retain the map-centred workspace, while giving operators a clearer starting point for routine work:
Health results and map views must remain labelled as stored-configuration analysis. They must not be presented as live BC authorization, current room state, or proof that a running bot adopted a saved value.
Make it immediately clear which record has unsaved changes, which fields will change, and what an operator must do next. Keep drafts in the current page session and provide clear return-to-draft navigation where practical. Do not persist drafts to local or session storage: drafts may contain sensitive configuration.
Keep the existing explicit review-and-confirm flow and expected-version checks. After a conflict, surface the latest-value comparison and explain that a save must be reviewed again; never merge or retry a write silently.
Audit complete administration flows, including search, record selection, validation, review, conflict resolution, and save confirmation. Ensure focus moves to newly displayed errors or review results, status changes are announced, and controls retain visible focus indicators. On narrow screens, prioritize the selected record and its actions, with map and secondary context available without forcing excessive scrolling.
Preserve the map editor’s existing keyboard operation and ensure the map is not the only way to locate or edit a record.
Define a small set of CSS custom properties for the existing palette, typography, spacing, borders, radii, focus rings, and semantic states. Use shared styles for buttons, navigation, panels, form fields, badges, notices, review diffs, and loading/empty states across the workspace, MOTD, appearance, recovery, account, and embedded map-analysis views.
The intent is to standardize repeated treatment, not to make distinct tools visually indistinguishable. Map brushes, selection overlays, and analysis visualizations should retain their specialized meaning while using the shared design language.
Use the same hierarchy for primary, secondary, and destructive actions, and the same visual and textual treatment for read-only access, editable access, unsaved drafts, pending saves, warnings, conflicts, and successful persistence. Pair color with text or an icon/label so state is not conveyed by color alone.
Keep the distinction between “saved to the database” and “adopted by the running bot” explicit wherever status is shown.
Treat responsive behavior, readable content density, semantic headings, control labels, keyboard operation, and contrast as shared component requirements. Validate the full set of tabs and embedded views rather than styling only the main workspace.
Record initial navigation latency and response sizes before changing loading behavior. The workspace currently fetches its data and then requests the appearance catalog and itemsets serially. Consider loading independent required data concurrently and deferring catalogs or reference data until an editor needs them. Keep data cached only for the current page session, define refresh and invalidation behavior, and retain server-side validation as authoritative.
Do not trade correctness for fewer requests: a draft must still be checked against the current stored revision at save time, and failed or unavailable reference data must be reported rather than treated as valid or complete.
Introduce a small dependency-free browser API helper for common JSON requests,
authentication-expiry notification, bounded error parsing, and cancellation of
obsolete reads. Migrate one editor at a time. Keep writes explicit, non-retrying,
and no-store; a shared helper must not hide endpoint-specific conflict or
validation behavior.
Gradually split the large workspace client into cohesive modules for workspace state/navigation, record listing and selection, forms and review, map presentation/editing, and analysis integration. Keep a narrow workspace controller as the integration point and avoid shared mutable globals across modules.
Apply the same incremental approach to the server-side workspace code: separate resource projections and validation from resource-specific mutation rules where that improves clarity. Preserve the existing transaction boundary, revision checks, sanitized audit writes, database isolation, and authorization gates. Do not introduce a framework, state-management package, or general-purpose database abstraction for this work.
Use the existing Playwright browser tests and built-in Node test suite to cover the important operator paths: finding a record, editing and reviewing a draft, handling a stale version, losing authentication, and using the interface at small viewport sizes. Add coverage alongside each module extraction or loading change. Establish any performance budgets from a representative baseline rather than choosing arbitrary thresholds.