How sourishmerugu/youtube-playlist-time-calculator works
1. This is a small, single-purpose Node.js application with two execution modes: a local Express server for development and a serverless API entrypoint for Vercel deployment.
2. The user-facing part is a static frontend in public/:
- public/index.html provides the page shell.
- public/script.js handles browser-side interaction, including extracting the playlist ID from a YouTube URL and calling the backend API.
- public/style.css contains presentation only.
3. The main backend responsibility is to calculate total playlist watch time from the YouTube Data API v3. There is no database or persistent storage; every request is computed live from YouTube API responses.
4. index.js appears to be the core shared business logic. Per the README, this is where the primary playlist-processing logic lives and is reused by the Express API. This is likely where playlist fetching, pagination, duration parsing, and total time calculation are implemented.
5. server.js is the local Express host. Its role is to:
- serve the static frontend from public/
- expose the API endpoint used by the browser
- invoke the shared logic in index.js
This is the boundary between the browser and the server-side YouTube API access.
6. api/playlist-time.js is a separate API handler for deployment on Vercel. It likely mirrors the Express route behavior but runs in a serverless context, using the same core logic so local and deployed behavior stay aligned.
7. The request flow is straightforward:
- user pastes a YouTube playlist URL in the browser
- frontend extracts playlistId
- frontend calls /api/playlist-time?playlistId=...&speed=...
- backend fetches playlist metadata and video durations from YouTube
- backend returns title, video count, total duration, and per-video details
8. The data-processing pipeline is important for architecture:
- playlist items are retrieved with pagination because playlists can exceed 50 videos
- video durations are fetched in batches of up to 50 IDs per API request
- ISO 8601 durations are parsed into seconds
- total time is aggregated and optionally adjusted by playback speed from 0.25x to 4x
9. dotenv and .env.example show that the YouTube API key is only used on the server side. The browser never receives the key, which is a critical security boundary in the design.
10. vercel.json ties the repo to Vercel’s routing/runtime conventions, indicating the same codebase supports both local Express hosting and serverless API deployment.
11. There are no message queues, caches, databases, or third-party backend services beyond the YouTube Data API. The architecture is essentially a thin UI layer plus a stateless computation/API layer.
12. For an architecture diagram, the main components to draw are:
- Browser UI in public/
- Local Express server in server.js
- Shared playlist-calculation module in index.js
- Vercel serverless API in api/playlist-time.js
- External YouTube Data API v3 as the only upstream dependency
- Environment variable source for the API key on the server side
Main entry points: index.js index.js · server.js server.js · playlist-time.js playlist-time.js · script.js script.js
Components 14
Browser UI
Static frontend served to the browser
- index.html · Browser page scaffold and form entrypoint
public/index.html - script.js · Extracts playlist IDs and calls the API
public/script.js - style.css · Presentation layer only
public/style.css
Local Server
Express host for development
- server.js · Serves static files and exposes the local API
server.js
Serverless API
Vercel entrypoint for deployed requests
- playlist-time.js · Vercel API endpoint for playlist timing
api/playlist-time.js
Shared Core
Reusable playlist-processing logic
- index.js · Common playlist-processing business logic
index.js - Playlist fetcher · Reads playlist items across pages
- Video batcher · Fetches video durations in batches
- Duration parser · Converts ISO 8601 durations into seconds
- Time aggregator · Totals watch time and applies playback speed
Deployment Config
Runtime and routing configuration
- .env.example · Documents server-side YouTube API key setup
.env.example - package.json · Dependencies and start scripts
package.json - vercel.json · Routes the app to Vercel runtime conventions
vercel.json
Other components
- YouTube Data API · Upstream source for playlist and video metadata
Connections 21
- index.html → script.js: loads · Page shell includes the browser client
- index.html → style.css: styles · Page shell applies static styling
- script.js → server.js: local API · Browser calls the Express endpoint during development
- script.js → playlist-time.js: deployed API · Browser calls the serverless endpoint in production
- server.js → index.html: serves · Express serves the frontend shell
- server.js → index.js: uses · Local API delegates playlist computation to shared logic
- playlist-time.js → index.js: uses · Serverless API delegates playlist computation to shared logic
- index.js → Playlist fetcher: orchestrates · Shared engine coordinates playlist retrieval
- index.js → Video batcher: orchestrates · Shared engine coordinates video duration lookup
- index.js → Duration parser: orchestrates · Shared engine normalizes ISO durations
- index.js → Time aggregator: orchestrates · Shared engine produces total and adjusted watch time
- Playlist fetcher → YouTube Data API: playlist items · Fetches paginated playlist metadata from YouTube
- Video batcher → YouTube Data API: video details · Fetches video durations in batches
- Duration parser → Time aggregator: seconds · Parsed durations feed the final calculation
- server.js → YouTube Data API: server-side access · Local server talks to YouTube without exposing the API key
- playlist-time.js → YouTube Data API: server-side access · Serverless handler talks to YouTube without exposing the API key
- .env.example → server.js: configures · Documents the API key required by the local server
- .env.example → playlist-time.js: configures · Documents the API key required by the serverless handler
- vercel.json → playlist-time.js: routes to · Maps deployment traffic to the Vercel function
- package.json → server.js: starts · Defines the Node runtime entrypoint and dependencies
- package.json → playlist-time.js: bundles · Provides shared dependencies for the serverless build