Spotify Data Tool (Musicality & Song Nutrition Facts) — Portfolio Context & Design Principles

The Spotify Data Tool (also known as the Musicality Dashboard or Song Nutrition Facts Generator) is an advanced, event-driven web application that transforms user streaming history and Spotify Wrapped data into deep interactive insights and playful, FDA-style "music nutrition labels."

---

🎯 Product Context

Music streaming apps show users basic listening summaries at the end of the year, but they often miss the deeper emotional and structural qualities of the music. The Spotify Data Tool addresses this by enriching standard listening data with detailed track analytics, lyrics analysis, and AI interpretation, compiling everything into a comprehensive data story.

Core Features

• Song Nutrition Facts Label: Generates a complete FDA-style food label detailing a song's structural ingredients (Groove as "Total Fat", Sweetness as "Carbohydrates", Structure as "Fiber", Depth as "Protein", Sharpness as "Sodium") along with badges for prosody, hook efficiency, lexical grade, and an AI nutritionist's note.
• Musicality Dashboard: Displays historical analytics including listening hour trends, temporal listening distributions (morning vs. night owl indicators), genre distributions, and unique achievements.
• Music Profile Clubs: Categorizes listening habits into curated communities (such as the Cloud State Society) with specific roles (e.g., active listeners) and chaos ranking scores.
• Natural Language Music Assistant: Includes an interactive chat helper allowing users to query their music history using natural language (e.g., "What album did I listen to most in August?" or "Am I a morning listener?").

---

🏗️ Multi-Agent Event-Driven Architecture

The core of the Spotify Data Tool is a decoupled, event-driven multi-agent system. Individual domain agents communicate asynchronously via an Event Bus, isolating concerns and ensuring high scalability.

flowchart TD
    EB[Event Bus] <--> Orchestrator[Orchestrator]
    
    %% Ingestion Agents
    SpotifyAgent[Spotify Ingestion Agent] -->|TrackDataEvent| EB
    GeniusAgent[Genius Ingestion Agent] -->|LyricsEvent| EB
    
    %% Processing Agents
    EB -->|Trigger Ingestion| SpotifyAgent
    EB -->|Trigger Ingestion| GeniusAgent
    
    EB -->|Track & Lyrics| AIAgent[AI Analysis Agent - Claude]
    AIAgent -->|AnalysisEvent| EB
    
    EB -->|Analysis & Raw Data| NutritionAgent[Nutrition Generator Agent]
    NutritionAgent -->|NutritionLabelEvent| EB
    
    %% Output
    EB -->|Final Label| FormatterAgent[Result Formatter Agent]
    FormatterAgent -->|Rendered View| Client([Client Dashboard])

Active Agents & Roster

1. Event Bus (core/orchestrator/event-bus.ts): Handles publish/subscribe patterns, priority messaging, error isolation, and metrics collection.
2. Spotify Ingestion Agent (core/agents/ingestion/spotify-agent.ts): Fetches user playlists, track metadata, and acoustic audio features via the Spotify API.
3. Genius Ingestion Agent (core/agents/ingestion/genius-agent.ts): Fetches track lyrics and calculates lexical indices (word counts, diversity).
4. AI Analysis Agent (core/agents/processing/ai-analysis-agent.ts): Orchestrates prompts to Claude Sonnet to extract sentiment, emotional prosody, and structural hook strength.
5. Nutrition Generator Agent (core/agents/processing/nutrition-generator-agent.ts): Normalizes the combined API and AI outputs to compile the values, badges, and labels for the FDA nutrition cards.

---

🎨 Design Principles & Aesthetics

The UI is optimized to provide a premium, highly engaging user experience:

• FDA-Style Nutrition Card: Designed to look exactly like a physical food label, adding a tactile element to the digital charts. It includes thick divider lines, nutrition percentages based on genre averages, and ingredients lists.
• Aesthetic Color Harmony: Uses a sleek, dark canvas (#050508) paired with neon-green (#1ED760), orange (#FF6B35), purple (#A78BFA), and blue (#3B82F6) gradients.
• Glassmorphism Panels: Data panels use translucent background cards with blur filters and light borders, creating a modern layered look.
• Interactive Visualizations: Includes fully responsive Recharts line, bar, and pie charts that reveal data values on hover.
• Scroll Reveal Animations: Custom hooks trigger entrance transitions, drawing the user's eye as they scroll down the dashboard.

---

🛠️ Technology Stack

• Frontend: Next.js (React), TypeScript, Recharts, Lucide Icons, Vanilla CSS.
• Backend: Node.js, Next.js API Routes, TypeScript.
• External Integrations: Spotify Web API (via OAuth), Genius API, Anthropic Claude API.
• Core Abstraction: Custom Event Bus & Orchestrator.