CableGUI/CLAUDE.md

mCables — Project Instructions

Project Overview

Cable-management framework for m's setup. Each cable-managed environment (LOFT, OFFICE, …) is a separate mCables project, and each project is backed by exactly one Excalidraw drawing. The framework provides a visual web interface backed by a Go HTTP API and SQLite, plus an export pipeline that writes .excalidraw files via mExDraw.

Memory group_id: mcables

No CLI. Frontend-first — every interaction is through the visual interface. The backend serves the UI and the API; there is no mcables shell binary intended for humans.

Goal

• A reusable framework for tracking devices, ports, cables, cable types, bundles, frames — scoped per project (LOFT and OFFICE are separate projects, each a separate drawing).
• A visual editor in the browser: switch projects, add frames/devices/ports, click ports to wire up cables, pick cable types from a per-project legend.
• A one-way export from the DB to the corresponding .excalidraw drawing on mxdrw.msbls.de whenever m clicks Export — DB is authoritative, Excalidraw is the projection.
• Bundle detection: parallel cables along the same path within a project get grouped + colour-bundled in the diagram.

Architecture

Layer	Tech	Notes
DB	SQLite	./data/mcables.db (project-local, gitignored). Driver: modernc.org/sqlite (cgo-free).
Backend	Go	net/http HTTP API + static frontend via embed.FS. Standard library + minimal deps. Single binary.
Frontend	Vanilla JS modules + SVG, no build step	TypeScript types via JSDoc, optional tsc --noEmit in CI. Preact-via-CDN-ESM is the documented fallback if vanilla state gets painful — no build step either way.
Diagram I/O	mExDraw HTTP API	PUT https://mxdrw.msbls.de/api/drawings/<name>.excalidraw with Authorization: Bearer $MEXDRAW_TOKEN. (The mcp__mexdraw__* MCP tools are not currently configured for this project — workers use the raw HTTP API.)

Hierarchy

• Project (projects table) is the top-level concept. LOFT, OFFICE, HOMELAB, … are separate projects. One project ↔ one .excalidraw drawing in mExDraw. projects.drawing_name defaults to <name>.excalidraw server-side when omitted on create; editable later.
• Frames sub-divide a project (LOFT has desk, rack, media; OFFICE has desk, server). Frames are not projects — they're zones within one drawing.
• Every device, port, cable, IO marker, and bundle is project-scoped (project_id denormalised onto every row, with ON DELETE CASCADE from projects). UNIQUE (project_id, devices.name) — no two devices in one project share a name.
• Cable types are global. A single shared cable_types table — no project_id. The five defaults (Power/USB/HDMI/DP/RJ45) are seeded by migration 001 once, not per project. Renaming or recolouring a type affects every project's legend immediately.
• Project deletion guardrail. DELETE /api/projects/:pid requires ?confirm=<name> matching the project's current name. 400 otherwise.

Branch Strategy

• main = production-deployable.
• mai/<worker>/<slug> = worker branches via the mai workflow.
• No dev branch — too small a project for staging.
• Merge with --no-ff to main, delete branches after merge.

Tech Stack

• Go for the backend (matches m's other tools: m, mai, youpcms, mExDraw).
• SQLite via modernc.org/sqlite (cgo-free → clean scratch/distroless container, no toolchain pain).
• mExDraw via HTTP for diagram export. Never edit raw .excalidraw files directly outside the mExDraw API.
• Vanilla JS + SVG for the frontend — no build step. JSDoc-typed.

Deployment — mDock, raw docker (NOT Dokploy)

mCables runs on mDock (192.168.178.131 on the LAN, Tailscale mdock) as a plain docker-compose service. Dokploy is for public mlake/mRiver stuff; mDock uses raw docker compose per the conventions of the existing mDock services (mgreen, mgeo, msports-garmin, paperless, …).

• Repo layout on mDock: /home/m/stacks/mcables/ with docker-compose.yml, data/ bind-mount, secrets in /home/m/secrets/mcables/.env.
• Image: mgit.msbls.de/m/mcables:latest (built and pushed by a Gitea Actions workflow on push to main, runs on the self-hosted runner on mDock with label self-hosted:host).
• Port mapping: 7777:7777, exposed on the LAN — no reverse proxy.
• Restart policy: unless-stopped.
• LAN URL: http://mdock:7777.
• No auth — LAN-trusted.

Local dev (no Docker): go run ./cmd/mcables against ./data/mcables.db.

Seed drawing — visual grammar reference, not a runtime importer

mxdrw.msbls.de/draw/Cable-Management.excalidraw is reference material only. mCables does not auto-ingest it. m will rebuild LOFT and OFFICE from scratch inside the tool — the seed exists so the exporter mimics its visual grammar:

• Devices = rectangles with a text label.
• Ports = small ellipses (~12×9) positioned on a device edge. Positional, not containerId-bound. Stroke colour = cable type.
• Cables = arrows with startBinding / endBinding to ports or devices or IO diamonds.
• Cable types = colour, with a legend at the top-left of the project's first frame listing the project's cable_types.
• IO markers = small diamonds. Semantically wall outlets / power entry points — a cable terminating at an IO marker means "this end is plugged into a wall socket outside the diagram". They are not inter-frame bridges and they do not pair up.
• Frames = sub-zones inside a project (desk, rack, media, …).
• Lines = decorative only (legend separators in the seed). Ignored on export.

Legend colours (global, seeded once by migration 001):

Type	Hex
Power	#e03131
USB	#2f9e44
HDMI	#1971c2
DP	#9c36b5
RJ45	#ffd500

Out of scope (v0)

• Multi-user. mCables is m-only.
• Auth / sharing — LAN-trusted on mDock.
• Mobile / responsive — desktop browser only.
• Cable inventory beyond visual structure (no length, no purchase history, no SKU). Strictly visual structure for v0.
• Import from .excalidraw at runtime. If a one-shot migration is ever needed, a separate mcables-migrate CLI tool is the right shape, not a hot API endpoint.

Worker Preferences

• First shift = inventor (design pass): conventions, schema, API, export pipeline, mDock deploy plan, UI flows, slices. Output: docs/design.md + open questions for m.
• Second shift = coder (after m's go on the design): bootstrap repo skeleton (Go module, SQLite migrations, server, exporter, frontend scaffold). Take slices 1–4 first (project CRUD, frames/devices, ports and cables, IO + cable-type editing); slice 5 (Excalidraw export) closes the round-trip.
• Use Sonnet for both — greenfield, structure matters more than depth.