[crivetimihai]

Admin UI Modularisation

The Problem

The original mcpgateway/static/admin.js was a 33,812-line monolithic file — all UI logic, state management, API calls, validation, and event handling in one place. It was untestable in isolation, slow to load, and impossible to maintain at scale.

---

What Was Done

1. Decomposition into 44 ES Modules (mcpgateway/admin_ui/)

The monolith was split into focused, single-responsibility modules across four conceptual layers:

Layer	Modules	Purpose
Foundation	bootstrap.js, appState.js, utils.js, constants.js, security.js	Shared primitives, state, XSS protection
Domain	tools.js, servers.js, teams.js, gateway.js, tokens.js, llmModels.js, llmChat.js, prompts.js, resources.js, users.js, roots.js, a2aAgents.js	Entity-level CRUD, testing, validation
Features	auth.js, filters.js, search.js, tabs.js, pagination.js, modals.js, logging.js, metrics.js, plugins.js, monitoring.js, etc.	UI concerns, cross-cutting features
Orchestration	initialization.js, events.js, app.js, formSubmitHandlers.js	Startup, HTMX delegation, chart registry

2. Facade Pattern (admin_ui/admin.js)

A single facade aggregates all 35+ module exports and exposes them onto the window.Admin namespace — preserving the existing HTML contract where HTMX/Alpine templates call Admin.editTool(...), Admin.showTab(...), etc. No template changes required.

index.js
  └─→ admin.js (facade)
        ├─→ bootstrap.js         (window.Admin = {})
        ├─→ utils.js, tools.js, servers.js ... (ES modules → Admin.fn = fn)
        ├─→ events.js            (IIFE, self-registers)
        └─→ app.js               (IIFE, self-registers)

3. Vite Build Pipeline

A new Vite configuration (vite.config.js) bundles admin_ui/index.js into an IIFE format output at mcpgateway/static/bundle-[HASH].js. The hash changes on every rebuild, providing automatic cache busting. External libraries (HTMX, Alpine, Chart.js, CodeMirror, DOMPurify) remain CDN-loaded and are declared as globals — not bundled.

Python's mcpgateway/admin.py reads the Vite manifest at startup to resolve the hashed filename, injecting it into the admin template as {{ bundle_js }}.

4. Test Suite: 20% → 70%+ Coverage

44 new Vitest unit test files in tests/unit/js/, one per module, using:

• jsdom environment to simulate the browser DOM
• vi.mock() for clean module isolation
• AppState.reset() in afterEach to prevent test pollution
• Istanbul as coverage provider (text + JSON + HTML + lcov reporters)

The vitest.config.js instruments only mcpgateway/admin_ui/**/*.js (not the compiled bundle), giving accurate per-module coverage.

5. Playwright Tests Maintained

End-to-end Playwright tests continue to pass at the same success rate — the public API (window.Admin.*) is unchanged, so browser-level test contracts were not broken by the refactor.

---

Key Design Decisions

• Sequential import order in the facade: bootstrap.js must initialise window.Admin before any module tries to write to it.
• IIFE for stateful orchestration (events.js, app.js): modules that need to self-register event listeners at load time use the IIFE pattern rather than pure ES module exports.
• No circular dependencies: appState.js acts as the shared hub; utils.js and constants.js have zero app-level dependencies; domain modules only import from the foundation layer.
• emptyOutDir: false in Vite config: preserves vendor files, images, and other static assets alongside the bundle.

---

File Map

Path	Description
mcpgateway/admin_ui/*.js	44 source modules (32,224 LOC total)
mcpgateway/admin_ui/index.js	Build entry point
mcpgateway/admin_ui/admin.js	Facade — aggregates all exports onto window.Admin
mcpgateway/admin.py	get_bundle_js_filename() — resolves hashed name at startup
mcpgateway/templates/admin.html	References {{ bundle_js }}
vite.config.js	Bundler configuration
vitest.config.js	Test runner configuration
package.json	Scripts and dev dependencies
tests/unit/js/*.test.js	44 Vitest unit test files

[vishu-bh]

LGTM

Ran admin UI locally and all looks okay.

[gcgoncalves]

@vishu-bh Rebased and resolved the secrets baseline conflict.

[marekdano]

LGTM 🚀