Data Flow

Relevant source files

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

• hooks/useContentGenerator.ts
• hooks/useNotes.ts
• hooks/useTranscript.ts
• services/geminiService.ts
• api/index.py
• App.tsx
• types.ts
• components/TranscriptColumn.tsx

The data flow in the youtube_notes application is a reactive, multi-stage process that transforms a YouTube video URL into a rich, interactive dashboard of AI-generated notes and content. The flow begins with user input, proceeds through a Python backend to fetch the video transcript, leverages the Google Gemini API for various content generation tasks, and culminates in the display and local persistence of the data in the React frontend.

The core of the application's data management is handled by a set of custom React hooks (useTranscript, useNotes, useContentGenerator) that orchestrate API calls, manage application state, and interact with the browser's localStorage for persistence. This architecture ensures a clear separation of concerns, where components are responsible for UI, and hooks manage the lifecycle of the data.

Initial Data Fetching: Transcript Loading

The primary data flow is initiated when a user submits a YouTube URL. This action triggers a chain of events to fetch the video's transcript, which serves as the foundational data for all subsequent AI processing.

The following diagram illustrates the sequence of operations for fetching a transcript.

This diagram shows the flow from user URL submission to the transcript being rendered.
Sources: App.tsx:32-39, hooks/useTranscript.ts:38-57, api/index.py:79-99, components/Header.tsx:34-42

Backend Transcript Endpoint

The frontend communicates with a Python FastAPI backend to retrieve the transcript. This is done to circumvent browser-based CORS issues and to potentially add a layer of caching or proxying.

Property	Description
Endpoint	/api/transcript
Method	GET
Query Parameter	videoId (string, 11 characters)
Success Response	200 OK with a JSON array of transcript segments ([{ "text": "...", "start": 0.0, "duration": 1.0 }]).
Error Responses	404 Not Found (Transcript unavailable), 429 Too Many Requests, 500 Internal Server Error.

The backend includes rate-limiting per IP address to prevent abuse.
Sources: api/index.py:26-42, api/index.py:79-99

Interactive AI Note Generation

Once the transcript is displayed, users can select a portion of the text to generate a concise, "cleaned" note. This is an interactive, on-demand data flow.

1. The user highlights text within the TranscriptColumn component.
2. A mouseup event listener detects the selection and captures the text, start time, and screen position.
3. The App component displays a FloatingActionButton near the selection.
4. Clicking this button triggers the handleAnalyze function, which calls the addNote method from the useNotes hook.
5. addNote calls geminiService.cleanTranscriptText, which sends the raw text to the Gemini API with a specific system instruction to summarize and correct it.
6. Upon receiving the cleaned text, a new Note object is created and saved to localStorage via storageService. The component state is updated, and the new note appears in the UI.

The sequence diagram below details this user-driven flow.

This diagram shows the process of creating a single AI-powered note from a text selection.
Sources: components/TranscriptColumn.tsx:100-125, App.tsx:50-63, hooks/useNotes.ts:28-54, services/geminiService.ts:18-56

Automated Smart Board Content Generation

In addition to manual note creation, the application automatically generates a "Smart Board" of content as soon as a transcript is successfully loaded. This process runs in the background without direct user interaction.

The useContentGenerator hook is responsible for this flow. An useEffect in App.tsx triggers the generateAll function when a new transcript becomes available. This function executes multiple asynchronous calls to the geminiService in parallel using Promise.allSettled to generate different types of content.

The following flowchart illustrates the parallel generation process.

This diagram shows how different content types are generated concurrently after the transcript is loaded.
Sources: App.tsx:42-48, hooks/useContentGenerator.ts:80-143, services/geminiService.ts:68-213

Each generation function in geminiService.ts uses a unique system instruction tailored to the desired output format (e.g., JSON for LinkedIn posts, a numbered list for Twitter threads).

Data Persistence and State Management

The application relies on the browser's localStorage for data persistence, ensuring that generated notes and content are not lost between sessions for a given video.

Data Models

The core data structures are defined in types.ts.

Interface	Fields	Description
Note	id, videoId, originalText, cleanedText, userNote, timestamp, createdAt	Represents a single user-generated, AI-cleaned note from the transcript.
ContentOutput	twitterThread, linkedInPost, blogOutline, keyTakeaways, generatedAt	A container for all auto-generated "Smart Board" content.
LinkedInPost	hook, body, cta, hashtags	Structured data for a LinkedIn post.
BlogOutline	title, sections, seoKeywords	Structured data for a blog post outline.
KeyTakeaway	emoji, text	A single, concise takeaway point.

Sources: types.ts

Local Storage Schema

Data is stored in localStorage using keys prefixed with tldw_content_ for Smart Board content and managed within the storageService.ts for notes (though the exact key for notes is abstracted by the service). The videoId is used as a unique identifier.

This ER diagram shows how notes and generated content for a specific video ID are structured within localStorage.
Sources: hooks/useContentGenerator.ts:33-51, hooks/useNotes.ts:23-25

The useContentGenerator and useNotes hooks automatically load data from localStorage when the videoId changes and save data back whenever the content or notes state is updated. This creates a seamless persistence layer.

Conclusion

The application's data flow is a well-orchestrated system that efficiently handles data from initial fetch to complex AI transformation and final persistence. It leverages a combination of a lightweight backend API, powerful frontend hooks for state management, and parallel processing to provide a responsive user experience. The flow is primarily unidirectional, starting from the video ID and branching out into transcript data, which then seeds multiple, independent AI generation and storage processes.