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

Local Web Interface

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.