# sourishmerugu/youtube-playlist-time-calculator architecture

> Architecture diagram of the GitHub repository sourishmerugu/youtube-playlist-time-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sourishmerugu/youtube-playlist-time-calculator
- Repository: https://github.com/sourishmerugu/youtube-playlist-time-calculator

## Overview

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`](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/index.js) (index.js), [`server.js`](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/server.js) (server.js), [`api/playlist-time.js`](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/api/playlist-time.js) (playlist-time.js), [`public/script.js`](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/script.js) (script.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_public_index_html["index.html<br/>page shell<br/>[index.html]"]
  node_public_script_js["script.js<br/>browser client<br/>[script.js]"]
  node_public_style_css["style.css<br/>styles<br/>[style.css]"]
end

subgraph group_local["Local Server"]
  node_server_js["server.js<br/>express host<br/>[server.js]"]
end

subgraph group_serverless["Serverless API"]
  node_api_playlist_time_js["playlist-time.js<br/>serverless handler<br/>[playlist-time.js]"]
end

subgraph group_core["Shared Core"]
  node_index_js["index.js<br/>shared engine<br/>[index.js]"]
  node_playlist_fetcher["Playlist fetcher<br/>pagination step"]
  node_video_batcher["Video batcher<br/>lookup step"]
  node_duration_parser["Duration parser<br/>time parser"]
  node_time_aggregator["Time aggregator<br/>calculation step"]
end

subgraph group_config["Deployment Config"]
  node_env_example[".env.example<br/>api key template<br/>[.env.example]"]
  node_package_json["package.json<br/>node manifest<br/>[package.json]"]
  node_vercel_json["vercel.json<br/>deploy config<br/>[vercel.json]"]
end

node_youtube_api[("YouTube Data API<br/>external service")]

node_public_index_html -->|"loads"| node_public_script_js
node_public_index_html -->|"styles"| node_public_style_css
node_public_script_js -->|"local API"| node_server_js
node_public_script_js -.->|"deployed API"| node_api_playlist_time_js
node_server_js -->|"serves"| node_public_index_html
node_server_js -->|"uses"| node_index_js
node_api_playlist_time_js -->|"uses"| node_index_js
node_index_js -->|"orchestrates"| node_playlist_fetcher
node_index_js -->|"orchestrates"| node_video_batcher
node_index_js -->|"orchestrates"| node_duration_parser
node_index_js -->|"orchestrates"| node_time_aggregator
node_playlist_fetcher -->|"playlist items"| node_youtube_api
node_video_batcher -->|"video details"| node_youtube_api
node_duration_parser -->|"seconds"| node_time_aggregator
node_server_js -->|"server-side access"| node_youtube_api
node_api_playlist_time_js -->|"server-side access"| node_youtube_api
node_env_example -.->|"configures"| node_server_js
node_env_example -.->|"configures"| node_api_playlist_time_js
node_vercel_json -.->|"routes to"| node_api_playlist_time_js
node_package_json -.->|"starts"| node_server_js
node_package_json -.->|"bundles"| node_api_playlist_time_js

click node_public_index_html "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/index.html"
click node_public_script_js "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/script.js"
click node_public_style_css "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/style.css"
click node_server_js "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/server.js"
click node_api_playlist_time_js "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/api/playlist-time.js"
click node_index_js "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/index.js"
click node_env_example "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/.env.example"
click node_package_json "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/package.json"
click node_vercel_json "https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/vercel.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_index_html,node_public_script_js,node_public_style_css toneBlue
class node_server_js toneAmber
class node_api_playlist_time_js toneMint
class node_index_js,node_playlist_fetcher,node_video_batcher,node_duration_parser,node_time_aggregator toneRose
class node_env_example,node_package_json,node_vercel_json toneIndigo
class node_youtube_api toneNeutral
```

## Components

### Browser UI

Static frontend served to the browser

- [index.html](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/index.html): page shell · Browser page scaffold and form entrypoint · `public/index.html`
- [script.js](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/script.js): browser client · Extracts playlist IDs and calls the API · `public/script.js`
- [style.css](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/public/style.css): styles · Presentation layer only · `public/style.css`

### Local Server

Express host for development

- [server.js](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/server.js): express host · Serves static files and exposes the local API · `server.js`

### Serverless API

Vercel entrypoint for deployed requests

- [playlist-time.js](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/api/playlist-time.js): serverless handler · Vercel API endpoint for playlist timing · `api/playlist-time.js`

### Shared Core

Reusable playlist-processing logic

- [index.js](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/index.js): shared engine · Common playlist-processing business logic · `index.js`
- **Playlist fetcher**: pagination step · Reads playlist items across pages
- **Video batcher**: lookup step · Fetches video durations in batches
- **Duration parser**: time parser · Converts ISO 8601 durations into seconds
- **Time aggregator**: calculation step · Totals watch time and applies playback speed

### Deployment Config

Runtime and routing configuration

- [.env.example](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/.env.example): api key template · Documents server-side YouTube API key setup · `.env.example`
- [package.json](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/package.json): node manifest · Dependencies and start scripts · `package.json`
- [vercel.json](https://github.com/sourishmerugu/youtube-playlist-time-calculator/blob/main/vercel.json): deploy config · Routes the app to Vercel runtime conventions · `vercel.json`

### Other components

- **YouTube Data API**: external service · Upstream source for playlist and video metadata

## Connections

- 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