A web application for guitarists to analyze chord progressions and discover compatible scales. Enter your chords, and Scale Scout will identify the key, suggest scales, and display them on an interactive fretboard.
Production URL: https://guitar-scale-scout-production.up.railway.app/
- Visual Chord Picker: Select root note, sharp/flat modifier, and chord type with intuitive buttons
- Text Input: Type chords directly (e.g., "C Am F G") with smart parsing
- Scale Analysis: Automatic key detection with confidence percentages and Roman numeral analysis
- Interactive Fretboard: Visual display with root notes highlighted, pentatonic mode, intervals mode, left-handed support
- Transposition: Transpose progressions up/down with buttons or keyboard shortcuts (Ctrl+Arrow)
- Mobile Responsive: Compact fretboard view with navigation on mobile devices
- Dark/Light Mode: Full theme support
- Shareable Links: URL parameters preserve chord progressions for sharing
- Node.js >= 20.0.0
- npm or bun
# Clone the repository
git clone https://github.com/SovereignSignal/guitar-scale-scout.git
cd guitar-scale-scout
# Install dependencies
npm install
# Start development server
npm run devThe app will be available at http://localhost:8080
| Command | Description |
|---|---|
npm run dev |
Start development server with hot reload |
npm run build |
Build for production |
npm run preview |
Preview production build locally |
npm run test |
Run unit tests in watch mode |
npm run test:run |
Run unit tests once (237 tests) |
npm run test:coverage |
Run unit tests with coverage report |
npm run test:e2e |
Run Playwright E2E tests against production |
npm run lint |
Run ESLint |
| Category | Technology |
|---|---|
| Framework | React 18 + TypeScript |
| Build Tool | Vite 5 |
| Styling | Tailwind CSS + shadcn/ui |
| State | React hooks + localStorage |
| Routing | React Router v6 |
| Unit Testing | Vitest + Testing Library |
| E2E Testing | Playwright |
| Deployment | Railway (via nixpacks) |
src/
├── components/ # React components
│ ├── ui/ # shadcn/ui base components
│ ├── Breadcrumb.tsx # Navigation breadcrumb
│ ├── ChordProgressionInput.tsx # Visual chord picker + text input
│ ├── ErrorBoundary.tsx # Error boundary wrapper
│ ├── Fretboard.tsx # Guitar fretboard visualization
│ └── ThemeToggle.tsx # Dark/light mode toggle
├── hooks/ # Custom React hooks
│ ├── use-debounced-state.ts
│ ├── use-mobile.tsx
│ └── use-toast.ts
├── lib/ # Utility functions
│ ├── scale-analysis.ts # Scale detection algorithm
│ ├── chord-utils.ts # Chord parsing/formatting
│ ├── transposition.ts # Key transposition logic
│ ├── url-utils.ts # URL parameter handling
│ └── security.ts # Input sanitization
├── pages/ # Route pages
│ ├── Hero.tsx # Landing page
│ ├── Index.tsx # Main app page
│ └── NotFound.tsx # 404 page
├── types/ # TypeScript type definitions
│ └── music.ts # Shared music types (Chord, Scale, etc.)
└── test/ # Test utilities
The app follows a simple unidirectional data flow:
User Input → ChordProgressionInput → Index.tsx (state) → scale-analysis.ts → Fretboard
- Index.tsx is the main orchestrator holding all app state
- scale-analysis.ts contains the scale detection algorithm (extracted for testability)
- Fretboard.tsx is memoized to prevent unnecessary re-renders
See ARCHITECTURE.md for detailed system design documentation.
The app is deployed on Railway using nixpacks for automatic builds.
railway.toml/railway.json: Railway-specific settingsnixpacks.toml: Build configuration- Production runs via
serve -s dist -l ${PORT:-3000}
No environment variables are required for basic functionality. The app is entirely client-side.
The project has comprehensive test coverage with 237 tests:
| Test File | Tests | Description |
|---|---|---|
scale-analysis.test.ts |
22 | Scale detection algorithm |
ChordProgressionInput.test.tsx |
21 | Chord input UI |
Fretboard.test.tsx |
22 | Fretboard rendering |
ErrorBoundary.test.tsx |
20 | Error handling |
url-utils.test.ts |
20 | URL parameter handling |
security.test.ts |
46 | Input sanitization |
chord-utils.test.ts |
28 | Chord parsing |
transposition.test.ts |
46 | Transposition logic |
use-debounced-state.test.ts |
12 | Debounce hook |
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is private.
- ARCHITECTURE.md - System architecture and design patterns
- CLAUDE.md - AI assistant onboarding guide
- IMPROVEMENTS.md - Planned features and specifications