docker-service-discovery/openspec/changes/archive/2026-03-27-modernize-frontend-ui/design.md

Context

The current frontend suffers from an outdated design, inconsistent clickable elements, and a lack of direct access for services not exposed through Traefik. This design document outlines the technical approach to modernize the UI, ensure comprehensive service accessibility, and achieve a professional aesthetic, thereby significantly enhancing the developer experience in local Docker environments.

Goals / Non-Goals

Goals:

• Modernize the user interface with a professional and polished look and feel.
• Ensure all relevant links are clickable and provide clear visual feedback.
• Implement a "frosted glass" effect for service cards to improve visual appeal and hierarchy.
• Provide direct, clickable access to services not exposed via Traefik, prioritizing local network accessibility.
• Improve overall frontend professionalism through refined typography, spacing, and responsive design.

Non-Goals:

• The core business logic or functionality of the backend services will not be altered, only their discovery and presentation.
• This tool will not manage Docker services (start, stop, restart). It remains read-only.

Decisions

1. Clickable Service Cards:

   • If a service has a traefikUrl, the entire service card will be a clickable link that opens the URL in a new tab.
   • If a service does not have a traefikUrl but has a preferredLocalUrl (an IP accessible from the client's subnet), the entire card will be a clickable link to this URL, opening in a new tab.
   • If neither a traefikUrl nor a preferredLocalUrl is available, the card will display all accessibleUrls (container IPs and ports) as a list of clickable links.

2. Frosted Glass Effect:

   • The frosted glass effect will be achieved using CSS backdrop-filter: blur().
   • A semi-transparent background color will be used to enhance the effect.

3. Frontend Styling:

   • A modern, clean font will be used.
   • The layout will be updated to be more spacious and visually balanced.
   • Implement a responsive design to ensure optimal viewing across various screen sizes.
   • Refine the color palette and spacing to contribute to a professional and polished appearance.

4. Backend IP Discovery:

   • The backend will use os.networkInterfaces() to identify its own local IP addresses and associated subnets.
   • For each container, the backend will iterate through its network settings to find all assigned IP addresses.
   • Logic will be implemented to compare container IPs against the backend's local subnets to determine a preferredLocalUrl.
   • The listContainers function will be modified to return traefikUrl, preferredLocalUrl, and a comprehensive list of accessibleUrls for each service.

Risks / Trade-offs

• [Risk] Browser compatibility for backdrop-filter.
  • Mitigation: A solid background color will be used as a fallback for browsers that do not support backdrop-filter.
• [Risk] Complexity of IP/subnet matching, especially across diverse Docker network configurations and host environments.
  • Mitigation: The initial implementation will focus on common local development setups (e.g., Docker bridge networks, host network mode). Further refinement may be needed for more complex scenarios.
• [Risk] Accurately determining the "client's subnet" if the client is not on the same host as the backend.
  • Mitigation: For the initial scope, the assumption is that the client is on the same local network as the backend. Future enhancements could involve client-side IP detection or configurable subnet ranges.