Frontend Services
Relevant source files
The following files were used as context for generating this wiki page:The frontend services layer forms the core logic and data handling backbone of the application. It abstracts interactions with external APIs, manages local browser storage, and orchestrates AI-powered content generation. These services are designed to be consumed by React hooks and components, providing a clean separation of concerns between the UI and the underlying business logic. The primary services include fetching YouTube video data, interacting with the Google Gemini API for content processing, and managing user settings and notes.
This architecture allows the UI to remain declarative, simply requesting data or actions, while the services handle the implementation details of network requests, data transformation, and persistence. The main services are YoutubeService, GeminiService, SettingsService, and StorageService, which are orchestrated by custom hooks like useTranscript, useNotes, and useContentGenerator.
Sources: services/youtubeService.ts, services/geminiService.ts, hooks/useContentGenerator.ts, hooks/useNotes.ts
YoutubeService
This service is responsible for all interactions related to YouTube video data, primarily fetching video transcripts.
Sources: services/youtubeService.ts
Key Functions
| Function | Description |
|---|---|
fetchTranscript(videoId) | Fetches the transcript for a given video ID by calling the application's backend API at /api/transcript. It validates the video ID format before making the request and handles potential network or backend errors. |
extractVideoId(url) | A static utility method that parses a YouTube URL (supporting various formats like watch?v=, youtu.be/, embed/) and extracts the 11-character video ID. |
Sources: services/youtubeService.ts:13-53, tests/youtubeService.test.ts:41-46
Transcript Fetching Flow
The diagram below illustrates the process of fetching a video transcript, from the initial API call to the final formatted data returned to the caller.
This diagram shows the flow for fetching a transcript via the YoutubeService.
Sources: services/youtubeService.ts:13-53
GeminiService
The GeminiService is the central hub for all AI-powered features, leveraging the Google Gemini API. It handles tasks such as cleaning transcript text and generating structured content for the "Smart Board".
Sources: services/geminiService.ts
Key Functions
| Function | Description |
|---|---|
cleanTranscriptText(rawText) | Takes a raw transcript snippet and uses Gemini to transform it into a concise, grammatically correct summary. |
validateApiKey(apiKey) | Sends a test request to the Gemini API to verify if a given API key is valid. |
generateTwitterThread(transcript) | Converts a full video transcript into a 7-10 tweet Twitter thread, formatted as a numbered list. |
generateLinkedInPost(transcript) | Generates a professional LinkedIn post from a transcript, returning a structured JSON object. |
generateBlogOutline(transcript) | Creates an SEO-optimized blog post outline from a transcript, also in a structured JSON format. |
generateKeyTakeaways(transcript) | Extracts 5-7 key takeaways from a transcript, returning a JSON array of objects with emojis and text. |
Sources: services/geminiService.ts:19-224
AI Content Generation Flow
The following sequence diagram shows the interaction when generating content, such as key takeaways. The process involves getting the API key, calling the Gemini API with a specific system instruction, and parsing the JSON response.
This diagram illustrates the sequence for generating AI content.
Sources: services/geminiService.ts:153-181, services/geminiService.ts:215-224
AI System Instructions
The service uses specific system instructions to guide the AI's output for different tasks. These instructions are critical for achieving the desired format and tone.
For cleaning transcript text:
You are an expert editor for video transcripts.
Your task is to take a raw snippet of text from a YouTube transcript (which may contain filler words, stuttering, or lack punctuation) and transform it into a concise, grammatically correct summary sentence or bullet point.
Retain the original meaning and context.
Do not add any introductory or concluding remarks. Just output the cleaned text.
Sources: services/geminiService.ts:4-10
For generating a LinkedIn post (output must be JSON):
You are a professional LinkedIn thought leader. Convert this video transcript into a compelling LinkedIn post.
Output EXACTLY in this JSON format (no markdown, no code blocks):
{"hook":"[Attention-grabbing first line]","body":"[3-4 paragraphs of value]","cta":"[Call to action]","hashtags":["tag1","tag2","tag3"]}
Sources: services/geminiService.ts:185-192
SettingsService
A lightweight service for managing application settings, specifically the user's Gemini API key. It uses localStorage for persistence.
| Function | Description |
|---|---|
setApiKey(key) | Saves the provided API key to localStorage. |
getApiKey() | Retrieves the API key from localStorage. |
Sources: services/settingsService.ts
StorageService
This service handles the persistence of user-generated notes. All data is stored in the browser's localStorage, scoped by video ID.
Sources: services/storageService.ts
Key Functions
| Function | Description |
|---|---|
getNotes(videoId) | Retrieves all notes for a specific videoId from localStorage. |
saveNote(note) | Adds or updates a note for a given videoId and saves the entire collection back to localStorage. |
deleteNote(videoId, noteId) | Removes a note with the specified noteId for a given videoId. |
Data Model
The service manages an array of Note objects for each video. The structure of a Note is defined in types.ts.
This diagram shows the entity relationship for the Note object.
Sources: types.ts:8-17, hooks/useNotes.ts:31-41
Service Orchestration by Hooks
The frontend services are primarily consumed by custom React hooks, which manage state and expose data and actions to the UI components. This creates a clear data flow from the service layer to the presentation layer.
This diagram shows how UI components use hooks, which in turn call the various frontend services.
Sources: App.tsx:14-17, hooks/useContentGenerator.ts, hooks/useNotes.ts, hooks/useTranscript.ts
The useContentGenerator hook is a prime example of orchestration. When its generateAll function is called, it triggers four parallel requests to the GeminiService to generate takeaways, a Twitter thread, a LinkedIn post, and a blog outline simultaneously. It manages the loading state for each and consolidates the results into a single ContentOutput object.
Sources: hooks/useContentGenerator.ts:88-142