feedBack/.specify/memory/constitution.md

FeedBack Constitution

FeedBack is a self-hosted, single-user web app for browsing, playing, and practicing interactive music notation, built around its own open .sloppak chart format (charts imported from Guitar Pro / MusicXML or authored in the built-in editor). This constitution captures the non-negotiable principles that govern its core (server.py, lib/, static/) and that all in-tree plugins (plugins/<name>/) inherit by default. It is a retrospective document — the codebase came first, the principles below were distilled from CLAUDE.md, README.md, and the shape of the existing implementation.

Core Principles

I. Self-Hosted, Single-User, Docker-First

FeedBack targets one user running one container against a personal song library folder. There is no multi-tenant model, no authentication, no rate limiting, and no shared backend. Deployment is expressed as a single docker compose up -d against the bundled Dockerfile; everything required (vgmstream, FFmpeg, FluidSynth, Python) is baked into the image so the host machine needs only Docker. Native (non-Docker) launch is supported for development but not the primary supported path.

Non-negotiable rules

• Do not introduce a user/account model, multi-tenant data partitioning, or auth middleware. All endpoints assume one trusted local user.
• New runtime dependencies (binaries, Python modules) must be installable inside the existing Dockerfile. If something cannot run in the container, it does not ship in core.
• DLC_DIR and CONFIG_DIR are the only required configuration inputs. Adding a new mandatory path/env var is a constitutional change.

II. Vanilla Frontend — No Frameworks

The frontend (static/app.js, static/highway.js, static/v3/index.html, static/style.css) is plain JavaScript with the fetch API, direct DOM manipulation, and the Canvas 2D / WebGL2 APIs. The only style framework is Tailwind CSS, served as a prebuilt static stylesheet (static/tailwind.min.css, regenerated by scripts/build-tailwind.sh) — never the runtime Play CDN, whose on-the-fly JIT rescans the DOM on the main thread and caused sustained frame drops with the 3D highway (feedBack-desktop#110). No React, Vue, Svelte, bundler, transpiler, or TypeScript appears in the core static tree, and no build step runs on the serve path: the Tailwind build is a maintainer-only one-shot whose output is committed, so Docker / desktop / end users never build. New features extend app.js and the existing globals (window.playSong, window.showScreen, window.createHighway, window.feedBack).

Native ES modules are a first-class, build-free extension mechanism. Because <script type="module"> and import are browser features — not a bundler — a large source file MAY be split into an import-ed module graph of plain source files, with no build step and no framework. A plugin opts in with "scriptType": "module" in plugin.json: its screen.js becomes a one-line import './src/main.js', and the host serves the src/ subtree from the sandboxed /api/plugins/<id>/src/… route and injects the entry as <script type="module">. The classic global-scope screen.js path remains fully supported; both coexist, and module scripts are still source-served — the no-bundler, no-transpiler, build-free-at-serve rule is unchanged. Core's own static/ tree may migrate to the same module-graph shape (static/js/…) over time under this rule.

Non-negotiable rules

• Do not introduce a frontend framework, JSX, or a JS build pipeline in core. Plugins MAY ship their own bundled assets but core MUST remain source-served.
• ES-module plugins remain source-served: no bundler or transpiler, and their own asset URLs (worklets, WASM, images) resolve via import.meta.url — never document.currentScript, which is null inside a module. scriptType:"module" and the optional minHost version floor are the only new plugin.json keys the module path adds.
• Because the core Tailwind stylesheet is prebuilt, it contains only the classes present in core source at build time. Core's committed static/tailwind.min.css MUST stay in sync with source — CI enforces this by rebuilding and diffing. A plugin that uses Tailwind classes not guaranteed in core (notably arbitrary values like w-[37px]) MUST ship its own compiled stylesheet via the styles capability, built with corePlugins.preflight = false so it emits only utilities and does not re-apply the base reset core already provides. Plugins MUST NOT load the Tailwind Play CDN (or any runtime CSS JIT) — the same no-CDN, build-free-at-serve rule that binds core binds plugins.
• New UI state lives in localStorage (or a backend endpoint), not in a framework store.
• Naming: camelCase JS, kebab-case CSS, snake_case plugin IDs. Player layout invariants (#player flex-column, #highway flex:1, #player-controls at the bottom) MUST be preserved.

III. Plugins Are the Extension Point — Isolated by load_sibling

Functionality that is not part of the irreducible "browse + play charts" loop ships as a plugin under plugins/<name>/, not as core code. Each plugin is its own directory (typically a separate git repo), discovered at startup via plugin.json, and free to add nav links, screens, settings panels, and /api/plugins/<id>/... routes. Plugins MUST isolate their backend Python imports via context["load_sibling"] so two plugins shipping a generic extractor.py / util.py / client.py do not collide in sys.modules.

Non-negotiable rules

• Generic features (practice journal, setlist, metronome, tone player, tab view, MIDI control, stem mixing, editors, etc.) belong in a plugin repo, not in lib/ or server.py.
• Plugin backend modules MUST use context["load_sibling"]("name") for sibling imports. Bare import sibling works during transition but triggers a startup warning when a name collides.
• Plugins MUST register routes under /api/plugins/<plugin_id>/..., use window.feedBack.emit/on for cross-plugin communication, and prefix their localStorage keys with their plugin id.
• Plugins inherit this constitution and may layer additional rules in their own CLAUDE.md, but MUST NOT relax core principles (e.g. a plugin cannot require a frontend framework in core).

IV. Backwards-Compatible Chart Library

The whole point of FeedBack is that a user points it at an existing song library folder and it Just Works. The library is scanned and indexed in meta.db (SQLite via MetadataDB). The open Sloppak format (lib/sloppak.py; specified at got-feedback/feedback-feedpak-spec, published as feedpak — same format) is the preferred format and the home for new features; loose-folder XML charts (lib/loosefolder.py) are also discovered and played as a first-class format. Both must keep playing across releases.

Non-negotiable rules

• Never modify, move, or delete files inside the user's library folder without an explicit user-initiated action (retune, edit metadata).
• A library scan MUST be non-blocking: the user can browse already- scanned songs while import continues. Scans MUST tolerate corrupt or partial files without aborting the batch.
• Schema migrations on meta.db MUST be additive and idempotent; unrecognized columns from a newer build MUST not crash an older one.
• Existing arrangement IDs, sloppak manifests, and the highway WebSocket message shape are stable contracts. Breaking changes require a CHANGELOG entry under "Migration notes".

V. Pure-Function Core Libraries, Tested

The shared Python in lib/ (song.py, tunings.py, sloppak.py, loosefolder.py, gp2rs.py, gp2midi.py, retune.py, etc.) is written as flat-importable, side-effect-light modules — no __init__.py package, no implicit IO at import time, no global mutable state beyond the explicit MetadataDB and config singletons in server.py. The pytest suite under tests/ covers pure-function helpers (note/tempo/ tick math, tuning lookups, song wire format) and runs in CI on every push and PR to main against Python 3.12.

Non-negotiable rules

• New lib/ modules MUST be importable with from <module> import X (flat imports, pyproject.toml sets pythonpath = [".", "lib"]).
• Pure helpers added to lib/ SHOULD ship with pytest coverage in tests/test_<module>.py. Network/filesystem-heavy code is exempt but should be split so the pure parts are testable.
• CI MUST stay green on main. A failing test on main is a P0.

VI. Observability Over Chattiness

All backend output goes through the stdlib logging pipeline configured by lib/logging_setup.py, controlled by LOG_LEVEL / LOG_FORMAT / LOG_FILE. Plugins receive a pre-configured context["log"] namespaced to feedBack.plugin.<id> and MUST use it instead of print. HTTP responses carry a X-Request-ID header from CorrelationIdMiddleware and the same id appears as request_id in JSON log lines. The "Settings → Export Diagnostics" bundle (lib/diagnostics_bundle.py) collects logs, hardware, plugin inventory, browser console, and per- plugin contributed diagnostics into a single redacted zip.

Non-negotiable rules

• New backend code MUST use logging.getLogger(...) (or the plugin context["log"]). print() and traceback.print_exc() are legacy and being migrated; do not add new ones.
• Diagnostic redaction is on by default. Anything that ships in the bundle (DLC paths, song filenames, IPs, bearer tokens) MUST be redacted via lib/diagnostics_redact.py rules before export.
• Plugins that contribute diagnostics MUST embed a versioned schema field (e.g. "my_plugin.diag.v1") and keep payloads under 100 KB. Diagnostics is not a backup channel — that is settings.server_files.

VII. Versioned, Migration-Aware Settings

User configuration lives in two places: server-side under CONFIG_DIR (SQLite meta.db, config.yaml, plugin opted-in files) and client- side in browser localStorage. Both can be exported and re-imported as a single bundle (POST /api/settings/import, GET /api/settings/export, feedBack#113). Import is two-phase: phase-1 validates the entire bundle (schema, paths, encoding) and phase-2 commits each file atomically via temp+rename. Plugins opt their server-side files into the bundle via settings.server_files in plugin.json (relpaths under CONFIG_DIR, no .., no absolute paths).

Non-negotiable rules

• Server-side settings imports MUST be all-or-nothing on safety-critical failures (path traversal, schema mismatch, decode failure). Plugin state mismatches between export and import are recoverable warnings, not hard failures.
• Plugins are responsible for their own internal data migration. Importing a bundle whose schema predates the running plugin's code MUST restore bytes verbatim — the plugin copes at next load.
• The VERSION file is the single source of truth for the running release; it is auto-bumped from feedBack-desktop releases via .github/workflows/sync-version.yml. Manual edits are reserved for out-of-band recovery only.

Operating Constraints

• Concurrency model: FastAPI + uvicorn, sync handlers for the bulk of routes, WebSockets for the highway data stream (/ws/highway/{filename}) and retune progress (/ws/retune). MetadataDB uses a threading.Lock; long-running work (rescan, retune, sloppak assembly) is dispatched via background threads or separate processes, never inline on the request path.
• Data flow: library folder → scan (sloppak.py / loosefolder.py) → MetadataDB (SQLite) → /api/library* → static/app.js → /ws/highway → static/highway.js. Sloppak arrangements are served from arrangements/<id>.json.
• Frontend layout invariants: #player is display:flex; flex-direction:column; position:fixed; inset:0; #highway is flex:1; #player-controls sits at the bottom. Hiding the highway collapses the layout — use margin-top: auto on controls if you need to hide it.
• Plugin load order: alphabetical by directory name. The playSong wrapper chain runs outermost-first (last-loaded wrapper runs first). Plugins MUST tolerate dependent globals being absent at load time and check at runtime (typeof window.X === 'function').
• Module load contract: a scriptType:"module" plugin is injected as <script type="module">, whose load event fires only after its whole static-import graph fetches and evaluates — so the loader's completion-by-onload guarantee (and the playSong wrapper-chain order above) is preserved exactly. The host loads screen.js once per version and showScreen re-injects nothing, so a plugin's per-visit re-initialization comes from its screen:changed handler, not from screen.js re-running; ES-module plugins inherit this unchanged (module top-level code does not re-execute on same-version re-mount).

Development Workflow

• Branching: never push directly to main. Always feature branch
  • PR. Exception: the automated VERSION bump from feedBack-desktop's release job, which commits to main as github-actions[bot].
• Reviews: PRs run the local Codex review loop (feedback_codex_preflight.md) and the GitHub Copilot review pass (feedback_copilot_review.md) before being eligible to merge. After pushing a fix, the CodeRabbit loop (feedback_coderabbit_review.md) runs to silence.
• Testing: pytest for backend (requirements-test.txt), Playwright for browser interactions (tests/browser/), CI runs both on every push/PR to main.
• CHANGELOG: every PR updates [Unreleased]. Releases rename [Unreleased] to [X.Y.Z] - YYYY-MM-DD (the VERSION bump itself is automated).
• Plugin gitlinks: plugins under plugins/ are typically separate git repos. Branch switches on the main repo can clobber plugin directories. Use git update-index --assume-unchanged and avoid git clean -fd near plugins/.

Governance

• This constitution governs the core repo (server.py, lib/, static/, tests/, .github/, Dockerfile, docker-compose.yml).
• Plugins inherit these principles by default. A plugin MAY add stricter rules in its own CLAUDE.md / README.md, but MUST NOT weaken a core principle. A plugin requesting a relaxation (e.g. shipping its own SQLite DB outside CONFIG_DIR) requires an explicit constitutional amendment in this file.
• Amendments require: (a) a PR that updates this file alongside the code change, (b) an entry in CHANGELOG.md under "Migration notes" if user-visible, and (c) a corresponding update to CLAUDE.md so AI agents and humans see the same source of truth.
• The principles are listed in priority order. When two principles conflict (e.g. "vanilla frontend" vs. a plugin that wants to ship React), the lower-numbered principle wins by default; the higher-numbered principle's escape hatch is to live in a plugin with its own bundled assets.

Version: 1.3.0 | Ratified: 2026-05-09 | Last Amended: 2026-07-11