Guitar Practice App
A personal, mobile-first practice and learning tool for guitar chord charts — in the
spirit of Ultimate Guitar Tabs, but built around your own charts. It never hosts
music for others: no public catalog, no sharing. Open source; run your own copy.
It started as a worship-team tool for one church and pivoted on 2026-09-28 (see
docs/DECISIONS.md D-22). See CLAUDE.md for scope and the
non-negotiables, and docs/ROADMAP.md for what's next.
What it does
- Song library — chord charts stored as ChordPro, searchable, exportable as
.pro.
- Transposition — render any chart in any key, with capo support.
- Viewer — chords above lyrics, with key / capo / render-mode controls
(
.../arrangements/[id]/view).
- Digitization — OCR your own paper charts into ChordPro, as a standalone
local script (not part of the web app).
- Planned — practice mode (metronome, autoscroll, looping), chord diagrams and
tabs, progress tracking, theory aids.
Services/setlists are still in the code from the church era, but retired.
Stack
Next.js (App Router) · TypeScript strict · Postgres (Neon) · Tailwind · shadcn/ui
(planned, ROADMAP Phase 0) · Vitest.
Migrations are plain numbered .sql files, forward-only — no ORM.
Getting started
npm install
Create .env.local with a Postgres connection string (no secrets in the repo):
DATABASE_URL=postgres://...
Apply migrations, then run the dev server:
npm run db:migrate # applies db/migrations/*.sql to DATABASE_URL from .env.local
npm run dev # http://localhost:3000
Everyday commands
| Command | Does |
|---|
npm run dev | Dev server |
npm test | Vitest (transposition has the densest suite in the repo) |
npm run lint | ESLint |
npm run build | Production build |
npm run db:migrate | Apply pending migrations to the local dev branch |
Digitization
The OCR import of paper chord charts is a standalone local tool:
scripts/digitize/, run via npm run digitize. Runbook:
scripts/digitize/README.md.
Docs
Load what a task needs, not all at once.
