LoothDB — The Luthier's Database

A workshop reference tool for luthiers and guitar techs: record clients, their guitars, and detailed per-guitar setup cards — and generate calibrated setup recommendations from the instrument's geometry.

Built by a guitar builder/tech (vintage Gibson specialty) as a single-file, dependency-free web app with a small PHP/SQLite backend.

What it does

• Clients → Guitars → Setup cards. Track each client's instruments and every setup you've done, with a per-guitar "current setup" card.
• Measurement protocol baked in — every card uses the same protocol, so cards are comparable across techs and time:
  • Relief @ 8th fret (capo 1, press 17)
  • Action @ 13th fret (capo 1), per string
  • Nut slot height @ 1st fret (open), per string
  • All values in decimal inches
• Setup Recommendation Engine (luthier-2.0.0): a physics-grounded, offline model that suggests relief, per-string action, and per-string nut heights from scale length, fretboard radius (including compound), neck joint fret, string gauges, tuning, fret condition, and the player's attack / buzz tolerance / technique / bend habits. Every recommendation carries a confidence score, ranges, warnings, and full provenance — they're starting targets, not gospel.
• String set management: factory sets (spans like 10-46 resolved to per-string gauges) plus named custom sets; gauge-span entry with geometric interpolation.
• Gauge adaptation: adapt a stored setup's measurements when a client changes string gauges — relief scaled by tension ratio, action/nut by per-string gauge ratio.
• Share links: publish a read-only setup card to a client via a token link (no login required on their end).
• Printable setup cards: clean print layout with the workshop ledger aesthetic (paper/brass/ink, Barlow + IBM Plex Mono).
• Photos: per-guitar photo gallery (downscaled JPEG) and PDF attachments with first-page thumbnails, plus a full-screen lightbox with a magnifier lens.
• Multi-tenant: per-company SQLite databases with full data isolation, user accounts, admin panel, session auth over secure cookies.

Screenshots

Clients list · a client's guitars · setup cards with the radius-arc glyph · the new-setup form with the recommendation engine · factory + custom string sets · the read-only shared setup view clients see via share link. (Demo data, captured from a local mock API.)

Architecture

loothdb.html          The entire app: HTML + CSS + vanilla JS (no frameworks,
                      no build step, hand-rolled DOM helper). The
                      recommendation engine lives between SETUP_ENGINE_START
                      and SETUP_ENGINE_END markers.
server/api.php        JSON API: auth, admin, KV store, share links.
server/bootstrap.php  One-time init: schema + first company/admin.
server/data/          auth.db + company_<id>.db (created at runtime;
                      configure location with LOOTHDB_DATA_DIR env var).
tests/                Node test suite (node:test) that extracts the engine
                      from loothdb.html and runs it in a VM — 187 tests
                      covering physics behavior, calibration parity, and
                      regression tests for confirmed bugs.
research/             Calibration data and analysis scripts behind the
                      engine's constants (Damron ORIGIN API harvest,
                      Erlewine nut-height specs, verification runs).

Running it

1. Copy loothdb.html to your web server docroot as index.html.
2. Place server/api.php next to it (or adjust the API constant in the HTML) and run php server/bootstrap.php <admin-password> once to create the schema and first admin user.
3. Requires PHP with PDO SQLite. Data lives in SQLite files under the data directory — put it somewhere backed up, outside the docroot.

The app itself is fully static: open the HTML, log in, and everything else runs client-side against the API.

Tests

node tests/setup-engine.test.js

187 tests, no dependencies beyond Node itself. The suite loads the real production engine out of loothdb.html, so it always tests what ships.

Engine design notes

The engine is a three-layer model — geometry, playability, preference — calibrated against harvested reference data (see research/) and published workshop specs (Erlewine nut heights), with explicit domain guards and disclosure warnings wherever it extrapolates beyond its calibration range. It runs entirely offline in the browser. Constants are documented with their provenance in the source; don't refit them without new calibration data.

Status

Personal workshop tool, actively used in daily bench work. Directions on the roadmap: repairs/fretwork logs, parts inventory, more string configurations (7-string, 12-string, baritone, 5/6-string bass).