songsense/ARCHITECTURE.md

SongSense Architecture

Project: /Users/jakeshore/.clawdbot/workspace/songsense

Stack: Next.js 15 + TypeScript + Tailwind CSS + Framer Motion

Shared Types: src/lib/types.ts (ALREADY CREATED - import from here)

Global CSS: src/app/globals.css (ALREADY CREATED - dark theme, purple accent)

Design: Dark mode, purple/pink gradient accents, modern glassmorphism cards

Color Palette:

• Background: #0a0a0f (primary), #12121a (secondary), #1a1a2e (cards)
• Accent: #8b5cf6 (purple), #ec4899 (pink), #f59e0b (amber)
• Text: #f0f0f5 (primary), #a0a0b8 (secondary)
• Use CSS variables from globals.css

Font: Inter from Google Fonts (already in globals.css)

File Ownership:

• BACKEND BUILDER owns: src/app/api/, src/lib/processing/, src/lib/store.ts, src/lib/queue.ts
• BACKEND REVIEWER owns: Reviews and improves all backend files
• FRONTEND BUILDER owns: src/app/page.tsx, src/app/layout.tsx, src/app/analyze/, src/app/review/, src/components/, public/
• FRONTEND REVIEWER owns: Reviews and improves all frontend files

Key Decisions:

• Use in-memory Map for job storage (MVP, no database needed)
• Use Server-Sent Events (SSE) for progress updates (simpler than WebSocket)
• Processing runs server-side via child_process (ffmpeg, whisper, songsense)
• File uploads stored in /tmp/songsense/
• Reviews stored in-memory Map
• No auth for MVP