Technical Debt Catalog

Purpose: Centralized tracking of known technical debt across the platform. Last Updated: February 2026

For actionable work items, create GitHub Issues with the tech-debt label.

🔴 High Priority

Scope: Core user navigation flows are incomplete or broken
Issues: Routing between views, back navigation, deep linking, breadcrumbs
Fix: Audit all navigation paths (dashboard → space → project → track → wave), document gaps, fix broken flows
Includes: URL identifier routing (shortId/slug), mobile navigation, tab persistence

2. Tailwind CSS v3 → v4 Visual Regression

Scope: Component backgrounds, spacing, colors broken after migration
Issues: Some components have wrong/missing backgrounds, opacity modifiers changed, dark mode behavior different
Fix: Visual audit of all key pages, fix broken utility classes
Reference: See PLAYER-COMPARISON.md for player-specific issues

3. Wave / Music Player Consolidation

Scope: wave-dashboard.tsx + new-wave-dashboard.tsx coexist, card.tsx + new-card.tsx, main-panel.tsx + new-main-panel.tsx
Also: Player component differences between reference branches and current code
Fix: Determine which version is active, remove or archive duplicates, stabilize player

4. Light/Dark Mode

Scope: Theme follows device preference but may not be fully implemented across all components
Issues: Some components may not respect prefers-color-scheme, manual toggle may be missing
Fix: Audit all components for theme support, ensure consistent dark/light mode rendering

5. Zero Test Coverage (incl. Performance)

Scope: No unit or integration tests in frontend. Only 1 spec file in backend.
Risk: Refactoring and feature additions are fragile.
Plan: Set up Vitest (frontend) and Jest (backend). Start with critical paths: auth, file upload, track CRUD.
Performance: Include Lighthouse CI benchmarks, bundle size tracking, load-time assertions

6. `s3Url` → `blobUrl` Rename ✅ DONE

Completed: February 2026 — renamed across 32 files (6 backend + 26 frontend)
Remaining: Run DB migration script (scripts/migrate-s3url-to-bloburl.js)

7. Type Safety Gaps

Scope: Many any types throughout frontend types/ directory
Examples: TTrack.credits: any, TTrack.attachments: any, INotification.data?: any
Fix: Define proper interfaces for all any typed fields

🟡 Medium Priority

8. Inconsistent Error Handling

Scope: Server actions use different error patterns (some throw, some return empty arrays, some console.error)
Fix: Create a unified apiCall() wrapper or use React Query error boundaries

9. Console.log Statements

Scope: Various files across frontend and backend
Fix: Replace with proper logger (Winston/Pino for backend, conditional logger for frontend)

Scope: Missing ARIA labels, keyboard navigation incomplete
Priority areas: Audio player controls, modal dialogs, form inputs

11. RBAC / Permission Framework

Scope: Per-entity collaborators[] array with roles — no centralized Team entity
Phase: Mid-term (after stabilization). Basic collaborator = freemium, Teams = premium
Plan: See RBAC-DESIGN.md for planning

🟢 Low Priority

12. API Error Messages

Scope: Backend error responses are raw/technical
Fix: User-facing error messages need polish for production

13. Naming Inconsistency

Scope: "Wavic", "Sonnance", "ctrl-audio" mixed across docs and code
Status: On hold until product name is finalized

14. Legacy Reference Branches

Scope: _reference/ folder contains 5000+ files from old branches
Fix: Archive to a separate repo or branch when no longer needed for comparison