serato-doctor/docs/design/web-interface.md

Local Web Interface

The generated concept above is the approved visual direction. The implemented UI keeps its hierarchy, palette, safety emphasis, health ring, diagnostic cards, and responsive behavior. Product truth takes precedence over mockup copy: a 77.8% library is labeled for review rather than described as healthy.

Problem

The command line is useful for automation but makes the growing diagnostic set harder to explore. A visual dashboard lets users test analysis safely and understand which findings affect health.

Architecture

serato-doctor-web binds to 127.0.0.1:8765 by default and serves package-owned HTML, CSS, and JavaScript with Python's standard library. A same-origin JSON endpoint runs the existing read-only parser, scanner, matcher, duplicate detector, crate classifier, and health engine. No web framework or external service is required.

The UI clearly labels read-only mode, separates scored health from informational diagnostics, and adapts from a full sidebar layout to compact mobile navigation.

Edge Cases

• Missing or invalid Serato and music directories.
• Empty libraries with no assessable health score.
• Large or malformed requests, capped at 64 KiB.
• HTML injection, avoided by rendering all results through textContent.
• Network exposure, avoided by a loopback-only default binding.

Verification

Tests exercise the web analysis adapter and static package assets. Browser checks cover real form submission, result rendering, error display, and responsive layout.