# Product

<!-- impeccable:product-schema 1 -->

## Platform

web

## Users

- Primary: dcntrlized node operators and self-hosters who run their own infrastructure and deploy services from the dcntrlized registry onto a Docker host. [Inferred from README positioning and docker-compose evidence; confirm.]
- Adjacent: developers and tinkerers evaluating Maestro and the dcntrlized ecosystem.

## Product Purpose

Maestro is the coordination layer of the dcntrlized ecosystem: a single web console that runs on a Docker host, lists the services installed on that node, lets the operator install new services from the dcntrlized container registry, and start, stop, update, and uninstall them. Success is a node operator managing the whole service stack from one console without dropping to the shell.

## Positioning

The mechanism is a Git-backed, decentralized service registry: services are published as OCI images with rich metadata in a Gitea registry, discovered through `/api/registry`, and installed by reference onto the node. The dashboard merges that remote catalog with the live local Docker state so installed services, available updates, and registry-only (not-yet-installed) services live in one view. Plainly: a decentralized app store that runs on your own hardware.

## Operating Context

- Web dashboard served from the Go backend on `:8080`, which talks to the local Docker socket.
- Live state flows over WebSocket (`ws://127.0.0.1:8080/api/ws`); the catalog is fetched once from `/api/registry`.
- Real-time statuses come from Docker (running, exited, stopped, created, restarting) plus UI states (installed, uninstalled).
- Service metadata (title, vendor, author, description, source, licenses, revision) comes from OCI annotations published with each image.
- Upstream registry is git.dcntrlized.org (Gitea), org `Dcntrlized`.
- Maestro itself runs as a container (image `maestro`); its own container is hidden from the list.
- Update detection compares the installed version against the registry latest via semver; versions are normalized to `X.Y.Z`.

## Capabilities and Constraints

- Capabilities: list installed + registry services; filter (all / running / updates / registry-only); search by name, image, or source; install, update (reinstall), start, stop, uninstall; live connection indicator; repository link per registry service.
- Constraints: browser talks to the backend on `127.0.0.1:8080` (dev proxy in Vite); no auth in the current UI; the data model merges local containers with remote registry items and must keep both sources distinct.
- Terminology: containers/services, registry, installed, running, "update available".

## Brand Commitments

- Name: Maestro. Organization: dcntrlized (lowercase, `.org`). Docker image name `maestro`.
- Open source (LICENSE present); dcntrlized ethos is decentralized, self-hosted, own-your-infrastructure.

## Evidence on Hand

- Backend Go source in `../src/` (handlers, lib) is the API and data-model truth.
- `services.json` at repo root lists registry examples: KeepNote (dcntrlized.org:8081), SafeGuard (dcntrlized.org:8082).
- README, docker-compose.yaml (mounts docker.sock, Gitea tokens), LICENSE.
- No DESIGN.md. Incumbent UI is a stock shadcn template — evidence of what it looked like, not authority over what it becomes.

## Product Principles

- Own your stack: the console runs on the node, beside the services it manages.
- One surface, live state: local Docker reality and the remote catalog appear in a single merged view.
- Act without the shell: install, start, stop, update, uninstall all happen from the UI.
- Honest status: every service shows a truthful current state and the action that fits it.

## Accessibility & Inclusion

- No product-specific requirement established yet; standard WCAG 2.x AA contrast and full keyboard support expected.