Frontend Overview

Relevant source files

The following files were used as context for generating this wiki page:

• App.tsx
• package.json
• index.html
• components/SmartBoard.tsx
• hooks/useContentGenerator.ts
• hooks/useNotes.ts
• hooks/useTranscript.ts
• services/geminiService.ts
• services/storageService.ts
• types.ts
• components/Header.tsx

The youtube_notes frontend is a single-page application built with React and TypeScript, designed to transform YouTube video content into structured, actionable intelligence. It provides a user interface for pasting a YouTube URL, viewing the video's transcript, and generating various forms of AI-powered content such as summaries, social media posts, and key takeaways. The application is a "Random Access Intelligence engine" that turns long-form video into a more digestible workspace.

The architecture is based on a modern frontend stack using Vite for building, Tailwind CSS for styling, and a set of custom React hooks for managing state and side effects. It integrates directly with the Google Gemini API to perform AI-driven text manipulation and content generation. All user-generated notes and AI content are persisted in the browser's localStorage for session continuity.

Sources: README.md, App.tsx, package.json, services/storageService.ts

Tech Stack and Dependencies

The frontend is built using a modern toolchain centered around React and Vite. Key dependencies are managed in package.json.

Library	Version	Description
react	^19.2.0	Core library for building the user interface.
vite	^6.2.0	Frontend tooling for development and building.
typescript	~5.8.2	Language for static typing.
@google/genai	^1.33.0	SDK for interacting with the Google Gemini API.
tailwindcss	^3.4.0	Utility-first CSS framework for styling (via CDN).
lucide-react	^0.554.0	Library for SVG icons.
react-youtube	^10.1.0	React component for the YouTube video player.
react-hot-toast	^2.6.0	Library for displaying notifications.
vitest	^4.0.16	Test framework for unit testing.

Sources: package.json:15-24, package.json:26-38, index.html:6-8

Application Architecture

The application follows a component-based architecture orchestrated by the main App.tsx component. State management is decentralized into custom hooks, each responsible for a specific domain (transcripts, notes, AI content).

Component Hierarchy

The diagram below illustrates the primary component structure of the application.

This diagram shows that the App component is the root, managing and passing data down to child components like Header, VideoPlayer, TranscriptColumn, and SmartBoard.

Sources: App.tsx:16-193

State Management & Data Flow

State is managed primarily through custom React hooks, which encapsulate logic for fetching data, interacting with services, and managing local state.

• useTranscript: Handles fetching and managing the video transcript.
• useNotes: Manages user-generated "margin notes," including creation (with AI cleaning), deletion, and loading from storage.
• useContentGenerator: Orchestrates the generation of high-level content (Twitter threads, blog outlines, etc.) via the Gemini API.

The following sequence diagram shows the primary user flow of loading a video and generating content.

Core Components

App.tsx

The root component that orchestrates the entire application. It initializes all custom hooks, manages the core state (videoId, selection), and renders the main layout. It is responsible for triggering data loading and content generation when a new video is loaded.

Sources: App.tsx

Header.tsx

This component contains the top navigation bar, including:

• An input field for the YouTube URL. It uses YoutubeService.extractVideoId to parse the ID from the URL.
• A settings button that opens a modal for entering and validating a Google Gemini API key.
• API key validation is performed by validateApiKey from the Gemini service.

Sources: components/Header.tsx:15-151

SmartBoard.tsx

A key UI component that displays all AI-generated content and user notes in a tabbed interface.

• Tabs: "Takeaways", "Thread", "LinkedIn", "Blog", and "Notes".
• It dynamically renders content based on the content and notes props.
• It shows loading states for each content type via the progress prop.
• It includes functionality to copy generated content to the clipboard.
• The "Notes" tab lists all NoteCard components and displays a processing indicator when a new note is being summarized by Gemini.

Sources: components/SmartBoard.tsx

NoteCard.tsx

A presentational component responsible for rendering a single note. It displays:

• The cleaned text of the note.
• The timestamp, which is clickable to seek the video (onJumpToTime).
• Action buttons for deleting (onDelete) and copying the note text.

Sources: components/NoteCard.tsx

AI Integration & Content Generation

The application's core intelligence comes from its integration with the Google Gemini API, managed through services/geminiService.ts and orchestrated by the useContentGenerator hook.

Gemini Service (geminiService.ts)

This service provides several functions that call the Gemini API with specific system instructions to generate different types of content. All functions use the gemini-2.0-flash model.

Function	System Instruction	Output Format
cleanTranscriptText	"You are an expert editor for video transcripts..."	A single, cleaned string.
generateTwitterThread	"You are a viral content creator for Twitter/X..."	An array of strings, parsed from a numbered list.
generateLinkedInPost	"You are a professional LinkedIn thought leader..."	A JSON object of type LinkedInPost.
generateBlogOutline	"You are an SEO content strategist..."	A JSON object of type BlogOutline.
generateKeyTakeaways	"You are a learning assistant..."	A JSON array of KeyTakeaway objects.

Sources: services/geminiService.ts:4-12, services/geminiService.ts:80-92, services/geminiService.ts:166-176, services/geminiService.ts:178-186, services/geminiService.ts:188-195

Content Generation Flow (useContentGenerator.ts)

The useContentGenerator hook manages the process of generating all "Smart Board" content. When generateAll is called, it triggers all Gemini service functions in parallel.

This flow ensures that all content types are requested simultaneously for efficiency and that the UI is updated progressively as results arrive.

Sources: hooks/useContentGenerator.ts:93-163

Data Models and Storage

The application defines its core data structures in types.ts and persists user data using localStorage via services/storageService.ts.

Core Data Types

The following diagram shows the relationships between the main data structures used in the application.

Local Storage

The storageService.ts abstracts localStorage interactions.

• Notes (tldw_notes): All notes are stored in a single JSON object, keyed by videoId. This allows notes to be retrieved per video.
• AI Content (tldw_content_ prefix): Generated content from the Smart Board is stored separately for each video, using a key like tldw_content_{videoId}. This caches the expensive AI generation calls.

Sources: services/storageService.ts:6, hooks/useContentGenerator.ts:58-60

Styling and UI

The UI is styled using Tailwind CSS, configured via a script in index.html. This configuration defines a custom theme with specific colors for yt (YouTube), background, surface, and primary elements, creating a cohesive dark-mode aesthetic. Custom scrollbar styles are also applied globally for a consistent look. Icons throughout the application are provided by the lucide-react library.

Sources: index.html:6-39, components/SmartBoard.tsx:10-29