# mattwright324/youtube-metadata architecture

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

- Interactive diagram: https://gitdiagram.com/mattwright324/youtube-metadata
- Repository: https://github.com/mattwright324/youtube-metadata

## Overview

1. **Overall shape**
   - This is a **static, client-side web app** for inspecting YouTube metadata, not a server-backed system.
   - The repository is organized like a **Jekyll site**: `index.html`, `bulk.html`, and `search.html` are the main entry pages, with `_layouts` and `_includes` providing shared page structure and form controls.

2. **Primary user-facing surfaces**
   - There are three main workflows:
     - **Single metadata lookup** on the main page
     - **Bulk metadata retrieval** in `bulk.html`
     - **Search-based discovery** in `search.html`
   - The README’s emphasis on shareable links and viewing “all metadata” suggests the app is designed around **URL-driven state** and reusable views.

3. **Core data source boundary**
   - The main external dependency is the **YouTube Data API v3**.
   - `js/youtube-api-v3.js` is the likely API access layer that handles request construction and result retrieval.
   - The app’s primary architectural boundary is therefore **browser UI → YouTube API → normalized metadata display**.

4. **Shared client-side application layer**
   - `js/shared.js` appears to hold common utilities used across all pages: shared state handling, formatting helpers, DOM wiring, and generic UI logic.
   - `js/translators.js` is a distinct enrichment layer for converting or interpreting values such as language/country codes and other API fields into human-readable forms.

5. **Single-item metadata workflow**
   - `js/youtube-metadata.js` is the core page controller for the main metadata experience.
   - From the README, this path takes a video, playlist, or channel identifier, fetches every available API part, and renders both raw and interpreted metadata.
   - This is the central “inspect one resource deeply” flow.

6. **Bulk retrieval workflow**
   - `js/youtube-metadata-bulk.js` supports batch input and multi-item extraction.
   - This subsystem exists for playlist/channel fan-out use cases, where the app enumerates many videos and gathers metadata at scale.
   - It likely shares the same API and formatting helpers, but with batch-specific progress and result aggregation logic.

7. **Search/discovery workflow**
   - `js/youtube-metadata-search.js` implements search-oriented discovery, likely querying YouTube search results and then drilling into returned items.
   - This page is a separate entry point because search has different input/output behavior than direct metadata lookup.
   - Architecturally, it sits beside the other flows rather than inside them, but still depends on the same shared API and UI utilities.

8. **Enrichment and investigative features**
   - The README highlights OSINT-oriented features: interpreting missing vs found fields, translations, geolocation links, reverse image search, and external lookup shortcuts.
   - Those are not separate services in this repo; they are **client-side enrichments** layered on top of API results and surfaced in the UI.
   - This means the app’s “processing” stage is mostly about **presentation and interpretation**, not backend computation.

9. **Import/export boundary**
   - The app supports exporting and importing data as **zip archives**, plus raw JSON and CSV.
   - `css/export.user.css` and the README’s export/import notes indicate a dedicated output path for archived/shareable datasets.
   - This creates a second major data flow: **API response → packaged export → later re-import into the same UI**.

10. **Presentation system**
   - `css/youtube-metadata.css` is the main application stylesheet; `css/export.user.css` is likely specialized for exported output or browser-user-style usage.
   - `_layouts/default.html` and `_includes/form_controls.html` / `_includes/formats.html` suggest the UI is built from reusable form and formatting partials.
   - The `img/` assets are part of the user-facing documentation and app branding, not core logic.

11. **Build and hosting model**
   - `Gemfile`, `_config.yml`, and the Jekyll directory structure show the site is built with the **Ruby/Jekyll toolchain**.
   - That means the repo likely produces a static site that can be hosted without a backend, with Jekyll assembling common page chrome and assets during build time.

12. **Important architectural takeaway**
   - The system is best understood as a **static, multi-page investigative frontend**:
     - Pages provide workflows
     - Shared JS provides common behavior
     - One module talks to YouTube
     - Separate modules handle single-item, bulk, and search flows
     - Enrichment/formatting stays in-browser
     - Export/import preserves data for offline or later review

Main entry points: [`index.html`](https://github.com/mattwright324/youtube-metadata/blob/main/index.html) (Main page), [`_layouts/default.html`](https://github.com/mattwright324/youtube-metadata/blob/main/_layouts/default.html) (Default layout), [`js/youtube-metadata.js`](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata.js) (Metadata flow), [`bulk.html`](https://github.com/mattwright324/youtube-metadata/blob/main/bulk.html) (Bulk page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & shell"]
  node_default_layout["Default layout<br/>jekyll layout<br/>[default.html]"]
  node_form_controls["Form controls<br/>include partial<br/>[form_controls.html]"]
  node_formats_partial["Formats partial<br/>include partial<br/>[formats.html]"]
  node_config["Site config<br/>jekyll config<br/>[_config.yml]"]
end

subgraph group_ui["User pages"]
  node_index_html["Main page<br/>entry page<br/>[index.html]"]
  node_bulk_html["Bulk page<br/>entry page<br/>[bulk.html]"]
  node_search_html["Search page<br/>entry page<br/>[search.html]"]
end

subgraph group_client["Client logic"]
  node_shared_js["Shared logic<br/>browser utils<br/>[shared.js]"]
  node_translators_js["Translators<br/>enrichment<br/>[translators.js]"]
  node_api_js["YouTube API<br/>api client<br/>[youtube-api-v3.js]"]
  node_metadata_js["Metadata flow<br/>single-item controller"]
  node_bulk_js["Bulk flow<br/>batch controller"]
  node_search_js["Search flow<br/>discovery controller"]
  node_examples_js["Examples<br/>sample data"]
end

subgraph group_assets["Assets"]
  node_main_css["App styles<br/>stylesheet"]
  node_export_css["Export styles<br/>stylesheet<br/>[export.user.css]"]
  node_img_asset["Brand assets<br/>image asset<br/>[icon.pdn]"]
end

node_default_layout -->|"wraps"| node_index_html
node_default_layout -->|"wraps"| node_bulk_html
node_default_layout -->|"wraps"| node_search_html
node_form_controls -->|"injects UI"| node_index_html
node_form_controls -->|"injects UI"| node_bulk_html
node_form_controls -->|"injects UI"| node_search_html
node_formats_partial -->|"injects UI"| node_index_html
node_shared_js -->|"supports"| node_metadata_js
node_shared_js -->|"supports"| node_bulk_js
node_shared_js -->|"supports"| node_search_js
node_translators_js -->|"enriches"| node_metadata_js
node_api_js -->|"fetches"| node_metadata_js
node_api_js -->|"fetches"| node_bulk_js
node_api_js -->|"fetches"| node_search_js
node_metadata_js -->|"powers"| node_index_html
node_bulk_js -->|"powers"| node_bulk_html
node_search_js -->|"powers"| node_search_html
node_examples_js -.->|"demonstrates"| node_index_html
node_main_css -->|"styles"| node_index_html
node_main_css -->|"styles"| node_bulk_html
node_main_css -->|"styles"| node_search_html
node_export_css -.->|"styles"| node_index_html
node_config -->|"configures"| node_default_layout
node_img_asset -.->|"brands"| node_default_layout

click node_index_html "https://github.com/mattwright324/youtube-metadata/blob/main/index.html"
click node_bulk_html "https://github.com/mattwright324/youtube-metadata/blob/main/bulk.html"
click node_search_html "https://github.com/mattwright324/youtube-metadata/blob/main/search.html"
click node_default_layout "https://github.com/mattwright324/youtube-metadata/blob/main/_layouts/default.html"
click node_form_controls "https://github.com/mattwright324/youtube-metadata/blob/main/_includes/form_controls.html"
click node_formats_partial "https://github.com/mattwright324/youtube-metadata/blob/main/_includes/formats.html"
click node_shared_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/shared.js"
click node_translators_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/translators.js"
click node_api_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-api-v3.js"
click node_metadata_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata.js"
click node_bulk_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-bulk.js"
click node_search_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-search.js"
click node_examples_js "https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-examples.js"
click node_main_css "https://github.com/mattwright324/youtube-metadata/blob/main/css/youtube-metadata.css"
click node_export_css "https://github.com/mattwright324/youtube-metadata/blob/main/css/export.user.css"
click node_img_asset "https://github.com/mattwright324/youtube-metadata/blob/main/img/icon.pdn"
click node_config "https://github.com/mattwright324/youtube-metadata/blob/main/_config.yml"

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_default_layout,node_form_controls,node_formats_partial,node_config toneBlue
class node_index_html,node_bulk_html,node_search_html toneAmber
class node_shared_js,node_translators_js,node_api_js,node_metadata_js,node_bulk_js,node_search_js,node_examples_js toneMint
class node_main_css,node_export_css,node_img_asset toneRose
```

## Components

### Build & shell

Jekyll/static site scaffolding and shared page chrome.

- [Default layout](https://github.com/mattwright324/youtube-metadata/blob/main/_layouts/default.html): jekyll layout · Shared page chrome and structure for the site. · `_layouts/default.html`
- [Form controls](https://github.com/mattwright324/youtube-metadata/blob/main/_includes/form_controls.html): include partial · Reusable input controls and form wiring. · `_includes/form_controls.html`
- [Formats partial](https://github.com/mattwright324/youtube-metadata/blob/main/_includes/formats.html): include partial · Reusable format and display templates. · `_includes/formats.html`
- [Site config](https://github.com/mattwright324/youtube-metadata/blob/main/_config.yml): jekyll config · Jekyll build configuration and site metadata. · `_config.yml`

### User pages

Main entry pages and workflow surfaces.

- [Main page](https://github.com/mattwright324/youtube-metadata/blob/main/index.html): entry page · Single-item metadata lookup and inspection surface. · `index.html`
- [Bulk page](https://github.com/mattwright324/youtube-metadata/blob/main/bulk.html): entry page · Batch metadata retrieval workflow. · `bulk.html`
- [Search page](https://github.com/mattwright324/youtube-metadata/blob/main/search.html): entry page · Search-driven discovery workflow. · `search.html`

### Client logic

Browser-side application modules for API access, shared behavior, and workflow controllers.

- [Shared logic](https://github.com/mattwright324/youtube-metadata/blob/main/js/shared.js): browser utils · Common utilities, state handling, and DOM helpers shared across pages. · `js/shared.js`
- [Translators](https://github.com/mattwright324/youtube-metadata/blob/main/js/translators.js): enrichment · Human-friendly interpretation of codes and metadata values. · `js/translators.js`
- [YouTube API](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-api-v3.js): api client · YouTube Data API v3 request construction and retrieval. · `js/youtube-api-v3.js`
- [Metadata flow](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata.js): single-item controller · Core single-resource lookup and metadata rendering workflow. · `js/youtube-metadata.js`
- [Bulk flow](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-bulk.js): batch controller · Multi-item extraction, fan-out, and aggregation workflow. · `js/youtube-metadata-bulk.js`
- [Search flow](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-search.js): discovery controller · Search-based discovery and drill-in workflow. · `js/youtube-metadata-search.js`
- [Examples](https://github.com/mattwright324/youtube-metadata/blob/main/js/youtube-metadata-examples.js): sample data · Example inputs and usage patterns for the app. · `js/youtube-metadata-examples.js`

### Assets

Styles and media used by the site and exports.

- [App styles](https://github.com/mattwright324/youtube-metadata/blob/main/css/youtube-metadata.css): stylesheet · Primary visual styling for the metadata interface. · `css/youtube-metadata.css`
- [Export styles](https://github.com/mattwright324/youtube-metadata/blob/main/css/export.user.css): stylesheet · Specialized styling for exported or user-style output. · `css/export.user.css`
- [Brand assets](https://github.com/mattwright324/youtube-metadata/blob/main/img/icon.pdn): image asset · Icon and visual assets used by the site and documentation. · `img/icon.pdn`

## Connections

- Default layout → Main page: wraps · Shared layout frames the main page.
- Default layout → Bulk page: wraps · Shared layout frames the bulk page.
- Default layout → Search page: wraps · Shared layout frames the search page.
- Form controls → Main page: injects UI · Reusable controls support the main lookup form.
- Form controls → Bulk page: injects UI · Reusable controls support batch input.
- Form controls → Search page: injects UI · Reusable controls support search inputs.
- Formats partial → Main page: injects UI · Shared formatting templates support metadata rendering.
- Shared logic → Metadata flow: supports · Shared helpers are used by the single-item controller.
- Shared logic → Bulk flow: supports · Shared helpers are used by the bulk controller.
- Shared logic → Search flow: supports · Shared helpers are used by the search controller.
- Translators → Metadata flow: enriches · Code and value translation enhances metadata display.
- YouTube API → Metadata flow: fetches · Single-item flow drives YouTube API requests.
- YouTube API → Bulk flow: fetches · Bulk flow reuses the same API client for fan-out retrieval.
- YouTube API → Search flow: fetches · Search flow queries YouTube through the API client.
- Metadata flow → Main page: powers · Main page controller powers single-resource lookup.
- Bulk flow → Bulk page: powers · Bulk controller powers the batch workflow.
- Search flow → Search page: powers · Search controller powers the discovery workflow.
- Examples → Main page: demonstrates · Example inputs help illustrate supported usage.
- App styles → Main page: styles · Primary stylesheet applies to the main experience.
- App styles → Bulk page: styles · Primary stylesheet applies to the bulk experience.
- App styles → Search page: styles · Primary stylesheet applies to the search experience.
- Export styles → Main page: styles · Export-oriented styling supports packaged output and review.
- Site config → Default layout: configures · Jekyll settings drive site assembly.
- Brand assets → Default layout: brands · Visual assets support the site shell and documentation.