PROJECT OVERVIEW:
The application, named MelodyMapper, aims to revolutionize guitar learning by moving beyond traditional tablature (tabs). It addresses the common problem of guitarists becoming overly reliant on tabs, hindering their ability to learn by ear and develop true musicality. MelodyMapper provides an interactive platform where users can listen to songs, transcribe them by ear using intelligent tools, and receive personalized feedback on their progress. The core value proposition is to empower guitarists to "hear" their way to mastery, fostering a deeper understanding of music and significantly improving their improvisation and ear-training skills.
TECH STACK:
- **Framework:** Next.js (App Router)
- **Styling:** Tailwind CSS
- **ORM:** Drizzle ORM (PostgreSQL compatible)
- **Database:** PostgreSQL
- **Authentication:** NextAuth.js (or Clerk for a more managed solution)
- **UI Library:** shadcn/ui (built on Radix UI and Tailwind CSS)
- **State Management:** React Context API or Zustand for simpler states, potentially Redux Toolkit for complex global states if needed.
- **Audio Processing:** Web Audio API for in-browser playback and analysis, possibly a backend service for more complex pitch detection/transcription if Web Audio API proves insufficient for MVP requirements.
- **Charting:** Recharts or Chart.js for visualizing progress.
- **Form Handling:** React Hook Form
- **Utilities:** Lodash, date-fns
DATABASE SCHEMA (PostgreSQL with Drizzle ORM):
1. **`users` table:**
- `id` (UUID, primary key, default gen_random_uuid())
- `name` (VARCHAR(255))
- `email` (VARCHAR(255), unique, not null)
- `emailVerified` (TIMESTAMPZ)
- `image` (VARCHAR(255))
- `createdAt` (TIMESTAMPZ, default now())
- `updatedAt` (TIMESTAMPZ, default now())
2. **`accounts` table (for NextAuth.js):
- `id` (BIGSERIAL, primary key)
- `userId` (UUID, foreign key to users.id, on delete cascade)
- `type` (VARCHAR(255), not null)
- `provider` (VARCHAR(255), not null)
- `providerAccountId` (VARCHAR(255), not null)
- `refresh_token` (TEXT)
- `access_token` (TEXT)
- `expires_at` (BIGINT)
- `token_type` (VARCHAR(255))
- `scope` (VARCHAR(255))
- `id_token` (TEXT)
- `session_state` (VARCHAR(255))
- `oauth_token_secret` (TEXT)
- `oauth_verifier` (TEXT)
- `created_at` (TIMESTAMPZ, default now())
- `updated_at` (TIMESTAMPZ, default now())
- `UNIQUE(provider, providerAccountId)`
3. **`sessions` table (for NextAuth.js):
- `id` (BIGSERIAL, primary key)
- `sessionToken` (VARCHAR(255), unique, not null)
- `userId` (UUID, foreign key to users.id, on delete cascade)
- `expires` (TIMESTAMPZ, not null)
- `created_at` (TIMESTAMPZ, default now())
- `updated_at` (TIMESTAMPZ, default now())
4. **`verificationTokens` table (for NextAuth.js):
- `id` (BIGSERIAL, primary key)
- `identifier` (VARCHAR(255), not null)
- `token` (VARCHAR(255), unique, not null)
- `expires` (TIMESTAMPZ, not null)
- `created_at` (TIMESTAMPZ, default now())
- `updated_at` (TIMESTAMPZ, default now())
- `UNIQUE(identifier, token)`
5. **`songs` table:**
- `id` (UUID, primary key, default gen_random_uuid())
- `title` (VARCHAR(255), not null)
- `artist` (VARCHAR(255))
- `audioUrl` (VARCHAR(255), not null)
- `difficulty` (VARCHAR(50))
- `genre` (VARCHAR(100))
- `createdAt` (TIMESTAMPZ, default now())
- `updatedAt` (TIMESTAMPZ, default now())
6. **`transcriptions` table:**
- `id` (UUID, primary key, default gen_random_uuid())
- `userId` (UUID, foreign key to users.id, on delete cascade, not null)
- `songId` (UUID, foreign key to songs.id, on delete cascade, not null)
- `userTranscriptionData` (JSONB, not null) - Stores user's transcribed notes, timing, pitch etc.
- `accuracyScore` (FLOAT)
- `feedback` (TEXT)
- `status` (VARCHAR(50), default 'in_progress') - e.g., 'in_progress', 'completed', 'needs_review'
- `createdAt` (TIMESTAMPZ, default now())
- `updatedAt` (TIMESTAMPZ, default now())
7. **`learning_progress` table:**
- `id` (UUID, primary key, default gen_random_uuid())
- `userId` (UUID, foreign key to users.id, on delete cascade, not null)
- `songId` (UUID, foreign key to songs.id, on delete cascade, not null)
- `lastPlayedTimestamp` (TIMESTAMPZ)
- `totalPlayTimeSeconds` (INTEGER)
- `transcriptionsCompleted` (INTEGER, default 0)
- `averageAccuracy` (FLOAT)
- `currentDifficultyLevel` (VARCHAR(50))
- `createdAt` (TIMESTAMPZ, default now())
- `updatedAt` (TIMESTAMPZ, default now())
- `UNIQUE(userId, songId)`
CORE FEATURES & USER FLOW:
1. **User Authentication:**
- Flow: User lands on the homepage. Clicks 'Sign Up' or 'Login'. Redirected to auth provider (e.g., Google, GitHub, email/password). After successful authentication, redirected to the dashboard.
- Edge Cases: Invalid credentials, email already exists, account lockout (future).
2. **Song Library & Playback:**
- Flow: Authenticated user navigates to 'Songs' page. Sees a list of available songs with title, artist, genre, difficulty. Filters/searches songs. Clicks a song. A modal or dedicated page opens with an audio player.
- Player Controls: Play, pause, seek bar, volume control, playback speed control (0.5x, 0.75x, 1x, 1.25x, 1.5x). Loop section functionality.
- Edge Cases: Audio file not loading, unsupported audio format (handle server-side), empty song library.
3. **Interactive Transcription Tool:**
- Flow: User clicks 'Transcribe' on a song. Enters the transcription interface. A timeline view displays the audio waveform. User listens to a section, attempts to play/input the notes (e.g., via a virtual fretboard, MIDI input, or direct note input). The tool provides real-time pitch/timing analysis against the original audio. User can mark sections as correct/incorrect, add notes. User saves their transcription progress.
- Transcription Input: Virtual guitar fretboard (selectable strings/frets), MIDI keyboard support, potentially a simple piano roll interface.
- Analysis: Real-time comparison of user input against the source audio's pitch and rhythm. Visual feedback (e.g., color-coding correct/incorrect notes).
- Saving: Transcriptions are saved incrementally via API calls, linked to the user and the song.
- Edge Cases: High latency for real-time analysis, inaccurate pitch detection for complex chords/harmonics, browser compatibility issues with Web Audio API.
4. **Progress Tracking & Feedback:**
- Flow: User navigates to 'Dashboard' or 'Progress'. Sees overview metrics (songs transcribed, accuracy score trends, time spent practicing). Clicks on a specific song's progress to see detailed feedback on their transcription attempts (e.g., common timing errors, pitch inaccuracies in specific sections).
- Feedback Mechanism: Accuracy score breakdown per section, identification of frequently missed notes or rhythmic patterns. Suggested exercises based on identified weaknesses.
- Visualizations: Charts showing accuracy over time, play time per song/genre.
- Edge Cases: No progress data available for new users, stale data updates.
API & DATA FETCHING:
- **Authentication:** API routes under `/api/auth/*` handled by NextAuth.js.
- **Songs:**
- `GET /api/songs`: Fetch list of songs (with filtering/pagination).
- `GET /api/songs/[id]`: Fetch details of a specific song.
- **Transcriptions:**
- `POST /api/transcriptions`: Create a new transcription entry (save progress).
- `PUT /api/transcriptions/[id]`: Update an existing transcription.
- `GET /api/transcriptions/user/[userId]`: Fetch all transcriptions for a user.
- `GET /api/transcriptions/song/[songId]`: Fetch transcriptions for a specific song (potentially filtered by user).
- **Progress:**
- `GET /api/progress/user/[userId]`: Fetch overall progress for a user.
- `GET /api/progress/user/[userId]/song/[songId]`: Fetch progress for a specific song.
- `POST /api/progress`: Update or create progress data (called after transcription saves).
- **Data Fetching Strategy:**
- Server Components for initial page loads (e.g., Dashboard, Song List) fetching data directly.
- Client Components for interactive elements (e.g., Audio Player, Transcription Tool) using `fetch` or libraries like SWR/React Query for dynamic data fetching and caching.
- API routes will handle database interactions using Drizzle ORM.
- Request/Response Bodies: JSON. For transcriptions, `userTranscriptionData` will be a complex JSON object representing notes, timing, velocity, etc.
UI/UX DESIGN & VISUAL IDENTITY:
- **Style:** Minimalist Clean with subtle futuristic/tech elements.
- **Color Palette:**
- Primary: Deep Navy Blue (`#0A192F`)
- Secondary: Cool Gray (`#8892B0`)
- Accent: Electric Cyan (`#64FFDA`)
- Background: Dark Charcoal (`#020C1B`)
- Text: Light Gray (`#CCD6F6`)
- **Typography:**
- Headings: 'Inter' (Variable Font,wght)
- Body: 'Inter' (Regular)
- **Layout:** Clean, spacious layout with clear visual hierarchy. Sidebar navigation for authenticated users. Main content area is dynamic.
- **Components:** Use shadcn/ui components for consistency (buttons, cards, modals, inputs, tables, progress bars, charts).
- **Animations:** Subtle fade-ins, slide-ins for elements appearing on scroll. Smooth transitions for route changes. Loading spinners/skeletons.
- **Responsive Rules:** Mobile-first approach. Fully responsive design adapting to all screen sizes (mobile, tablet, desktop). Navigation collapses into a hamburger menu on smaller screens. Transcription tool optimized for tablet/desktop use but accessible on mobile.
COMPONENT BREAKDOWN (Next.js App Router):
- **`app/layout.tsx`**: Root layout (<html>, <body>, global styles, providers like NextAuth, ThemeProvider).
- **`app/page.tsx`**: Landing Page (marketing content, value proposition, CTA for sign-up/login).
- **`app/auth/signin/page.tsx`**: Sign-in page (using NextAuth.js components or custom UI).
- **`app/(app)/layout.tsx`**: App Shell Layout (protected route wrapper, includes sidebar and main content area).
- **`app/(app)/dashboard/page.tsx`**: Dashboard (overview of progress, recent activity, quick links).
- Components: `WelcomeBanner`, `ProgressSummaryCard`, `RecentActivityFeed`, `QuickLinks`.
- State: Fetches user data and progress summaries.
- **`app/(app)/songs/page.tsx`**: Song Library (List of songs, search, filter, pagination).
- Components: `SongList`, `SongListItem`, `SearchBar`, `GenreFilter`, `DifficultyFilter`.
- State: Fetches song data, manages filter states.
- **`app/(app)/songs/[songId]/page.tsx`**: Song Detail Page / Transcription Entry Point.
- Components: `SongInfoCard`, `AudioPlayer`, `TranscriptionStartButton`, `ProgressBar` (for current song).
- State: Fetches song details, manages audio playback state.
- **`app/(app)/transcribe/[songId]/page.tsx`**: Interactive Transcription Interface.
- Components: `AudioVisualizer`, `TranscriptionTimeline`, `VirtualFretboard` (or other input method), `NoteInput`, `FeedbackDisplay`, `SaveButton`, `PlaybackControls`, `SectionMarker`.
- State: Manages audio playback, user input, real-time analysis, transcription data state, saving status.
- **`app/(app)/progress/page.tsx`**: Detailed Progress Page.
- Components: `OverallProgressChart`, `SongProgressTable`, `AccuracyTrendChart`, `FeedbackSection`.
- State: Fetches detailed progress and transcription history data.
- **`app/(app)/settings/page.tsx`**: User Settings Page.
- Components: `ProfileForm`, `AccountSettings`, `NotificationPreferences`.
- State: Manages user profile updates.
- **`components/ui/`**: Reusable shadcn/ui components and custom wrappers.
- **`lib/`**: Utility functions, API client, auth helpers, Drizzle DB connection.
- **`hooks/`**: Custom React hooks (e.g., `useAudioPlayer`, `useTranscription`, `useDebounce`).
ANIMATIONS:
- **Page Transitions:** `Framer Motion` for smooth cross-fade or slide animations between pages.
- **Element Loading:** Skeleton loaders (`react-loading-skeleton` or custom shadcn/ui variants) while data is fetching.
- **Interactive Elements:** Subtle hover effects on buttons and list items. Bounce or pulse animation for interactive tooltips or call-to-actions. Waveform visualization in the audio player with smooth rendering.
- **Saving Indicator:** A small animation (e.g., spinning icon, checkmark) to indicate successful saving of transcription data.
EDGE CASES:
- **Authentication:** Handle expired sessions, token refresh. Prevent access to protected routes without authentication. Implement `use client` directive appropriately for auth-dependent components.
- **Empty States:** Display informative messages and clear CTAs when song library is empty, no transcriptions exist, or no progress data is available (e.g., "Start your first transcription!", "No songs found matching your criteria.").
- **Data Validation:** Server-side validation for all API routes (using libraries like Zod with Drizzle).
- **Error Handling:** Graceful error handling for API calls (display user-friendly messages). Use `try...catch` blocks extensively. Implement global error boundary in React.
- **Audio Processing:** Handle potential errors during audio loading, playback, or analysis. Provide fallback messages. Ensure compatibility across browsers.
- **Transcription Data Integrity:** Implement checks to ensure the `userTranscriptionData` JSON structure is valid before saving or processing.
SAMPLE DATA:
1. **`users` Mock:**
```json
{
"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"name": "Alice",
"email": "alice@example.com",
"image": "/images/avatars/alice.png"
}
```
2. **`songs` Mock (for library):**
```json
[
{
"id": "s1",
"title": "Breaking the Law",
"artist": "Judas Priest",
"audioUrl": "/audio/breaking_the_law.mp3",
"difficulty": "Intermediate",
"genre": "Metal"
},
{
"id": "s2",
"title": "The Distance",
"artist": "Cake",
"audioUrl": "/audio/the_distance.mp3",
"difficulty": "Easy",
"genre": "Rock"
},
{
"id": "s3",
"title": "Imagine",
"artist": "John Lennon",
"audioUrl": "/audio/imagine.mp3",
"difficulty": "Easy",
"genre": "Pop"
}
]
```
3. **`transcriptions` Mock (User Alice, Song 'The Distance'):**
```json
{
"id": "t1",
"userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"songId": "s2",
"userTranscriptionData": {
"sections": [
{
"startTime": 0.5,
"endTime": 5.0,
"notes": [
{"pitch": 60, "timing": 0.8, "duration": 0.5, "velocity": 0.8, "accuracy": 0.9},
{"pitch": 62, "timing": 1.5, "duration": 0.5, "velocity": 0.7, "accuracy": 0.85}
]
}
]
},
"accuracyScore": 0.87,
"status": "completed"
}
```
4. **`learning_progress` Mock (User Alice, Song 'The Distance'):**
```json
{
"id": "p1",
"userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"songId": "s2",
"lastPlayedTimestamp": "2023-10-27T10:30:00Z",
"totalPlayTimeSeconds": 1200,
"transcriptionsCompleted": 2,
"averageAccuracy": 0.85,
"currentDifficultyLevel": "Easy"
}
```
5. **`transcriptions` Mock (Empty state for new user/song):
```json
{
"id": null, "userId": "...", "songId": "...", "userTranscriptionData": {"sections": []}, "accuracyScore": null, "status": "in_progress"
}
```
6. **`songs` Mock (Filtered result):
```json
[
{
"id": "s4",
"title": "Wish You Were Here",
"artist": "Pink Floyd",
"audioUrl": "/audio/wish_you_were_here.mp3",
"difficulty": "Intermediate",
"genre": "Rock"
}
]
```
7. **`learning_progress` Mock (No data yet):
```json
{
"id": null, "userId": "...", "songId": "...", "lastPlayedTimestamp": null, "totalPlayTimeSeconds": 0, "transcriptionsCompleted": 0, "averageAccuracy": 0.0, "currentDifficultyLevel": "Beginner"
}
```
8. **User Feedback Example:**
```json
{
"id": "t2",
"userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"songId": "s2",
"userTranscriptionData": {...},
"accuracyScore": 0.75,
"feedback": "Good effort on the main melody! Pay closer attention to the timing in measures 3-4, and try to hit the G# note more accurately. Consider slowing down playback for those sections.",
"status": "needs_review"
}
```
9. **`songs` Mock (Search Result):
```json
[
{
"id": "s5",
"title": "Stairway to Heaven",
"artist": "Led Zeppelin",
"audioUrl": "/audio/stairway_to_heaven.mp3",
"difficulty": "Advanced",
"genre": "Rock"
}
]
```
10. **`transcriptions` Mock (User providing input via Virtual Fretboard):
```json
{
"id": "t3",
"userId": "...",
"songId": "...",
"userTranscriptionData": {
"sections": [
{
"startTime": 10.0,
"endTime": 12.0,
"notes": [
{"fret": 5, "string": 2, "timing": 10.2, "duration": 0.4, "velocity": 0.7, "accuracy": null},
{"fret": 7, "string": 2, "timing": 10.7, "duration": 0.5, "velocity": 0.75, "accuracy": null}
]
}
]
},
"accuracyScore": null,
"status": "in_progress"
}
```