How darth-dodo/spotify-insights works
Project type and purpose
• This is a single-page React application (built with Vite) that serves as an analytics dashboard for Spotify users.
File structure
• Top-level:
• public, index.html, src/, docs/, .github/, config files (tsconfig, eslint, tailwind, vite).
• src/ splits into:
• components/ (UI components organized by feature: auth, dashboard, layout, ui primitives)
• hooks/ (React hooks for auth, theme, data, playback)
• lib/ (low-level wrappers around Spotify API, data fetchers, processors, cache, playback SDK)
• strategies/ (strategy pattern for auth and sandbox vs production data)
• pages/ (static routes: HelpPage, LegalPage, 404)
• styles/, main.tsx, App.tsx
• No backend code – all API interactions happen client-side via OAuth2 PKCE.
README for extra insights
• Tech stack: React 18, TypeScript, Vite, Tailwind CSS, React Query, Zustand, Shadcn/UI, Recharts, Framer Motion.
• Authentication: OAuth 2.0 PKCE against Spotify Web API.
• Data Flow: Custom data layer (lib/data) that fetches, processes, caches Spotify data, exposes to components via hooks.
a. Main components
1. User’s Browser / SPA
2. UI Layer (App, pages, components)
3. State & Data Layer
• React Query & Zustand stores
• Custom Hooks (useSpotifyData, useAuth, useToast, etc.)
4. Integration Layer (src/lib & strategies)
• Spotify-auth modules (spotify-auth-core, crypto, tokens)
• Spotify-data modules (fetcher, processor, cache, integration)
• Spotify-playback SDK & manager
• AuthStrategy & DataStrategy abstractions
5. External Services
• Spotify Authorization Server (OAuth2 endpoints)
• Spotify Web API (data endpoints)
6. Optional Local Storage / In-memory cache
b. Relationships and interactions
• UI components dispatch actions or call hooks → hooks consult React Query / Zustand → query functions in lib/data → call Spotify-data-fetcher → hit Spotify Web API → process & cache data → return to UI.
• Auth flow: UI triggers AuthProvider → strategy picks production or sandbox → PKCE handshake with Spotify Auth Server → receive tokens → store in cache → tokens used by data fetch calls.
• Playback flow: UI playback controls → hooks call spotify-playback-manager → playback-SDK injects script → events flow back to manager → UI updates.
c. Architectural patterns and principles
• Component-based UI (Shadcn/UI, custom layout & dashboard widgets)
• Provider pattern for cross-cutting concerns (AuthProvider, ThemeProvider, LoadingProvider)
• Strategy pattern for swapping auth/data implementations (sandbox vs production)
• Separation of concerns between UI, hooks, integration, and external communication
• Caching & data normalization in lib layer to optimize API usage
d. Key technologies / libraries
• React 18 + TypeScript + Vite
• React Query (async data) + Zustand (client state)
• Tailwind CSS + Shadcn/UI (styling & components)
• Recharts for charts, Framer Motion for animations
• OAuth2 PKCE modules in src/lib/auth
• Spotify-playback SDK in src/lib/playback
• Use clear labels: “Browser SPA,” “AuthProvider,” “Spotify Data Fetcher,” “Spotify Web API,” etc.
• UI → Hooks → Data Layer → External API
• UI → AuthProvider → Auth Server → Tokens → Data Layer
• Playback controls → Playback SDK → Browser Audio context
• “UI Layer,” “State & Hooks,” “Integration Layer,” “External Services.”