System Architecture Overview

Relevant source files

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

• App.tsx
• api/index.py
• services/geminiService.ts
• services/youtubeService.ts
• hooks/useContentGenerator.ts
• hooks/useNotes.ts
• hooks/useTranscript.ts
• components/SmartBoard.tsx
• package.json
• types.ts

The Nota application is designed to transform long-form YouTube video content into actionable, summarized intelligence. It achieves this through a client-heavy architecture that combines a React frontend for user interaction, a lightweight Python backend for fetching video transcripts, and direct integration with the Google Gemini API for AI-powered content generation and analysis. The system is built to provide a seamless workflow from pasting a YouTube URL to receiving structured content like key takeaways, social media posts, and contextual notes.

The architecture prioritizes a rich client-side experience, offloading transcript fetching to a serverless backend function to bypass potential browser restrictions (CORS) and handling all AI processing directly in the browser. This design allows for rapid UI updates and a responsive feel, with state management handled by a combination of React hooks and browser localStorage for persistence.

High-Level Architecture

The system is composed of three primary parts: a React-based frontend, a Python-based backend API, and external services for transcript and AI data.

The diagram below illustrates the main components and their interactions.

Frontend Architecture

The frontend is a single-page application built with React, TypeScript, and Vite. It is responsible for the entire user interface, state management, and interaction with external and backend services.

Sources: package.json, App.tsx

Core Components & Hooks

The application's logic is modularized into custom hooks, which manage specific slices of state and functionality. The main App.tsx component orchestrates these hooks and passes data down to presentational components.

Component/Hook	Description	Source File
App.tsx	The root component. Manages overall application state, orchestrates hooks, and renders the main layout.	App.tsx
useTranscript.ts	Manages fetching, loading state, and error handling for the video transcript.	hooks/useTranscript.ts
useNotes.ts	Manages the creation, storage, and deletion of "margin notes" generated from transcript selections.	hooks/useNotes.ts
useContentGenerator.ts	Manages the generation of all "Smart Board" content (Twitter threads, LinkedIn posts, etc.) by calling the Gemini service.	hooks/useContentGenerator.ts
SmartBoard.tsx	A UI component that displays all AI-generated content in a tabbed interface.	components/SmartBoard.tsx
youtubeService.ts	A service utility that handles fetching the transcript from the backend API and parsing YouTube URLs.	services/youtubeService.ts
geminiService.ts	A service utility that contains all logic for communicating with the Google Gemini API, including prompts and request configurations.	services/geminiService.ts

Frontend Data Flow

The following diagram shows the flow of data and actions within the frontend when a user loads a video and generates content.

Backend Architecture

The backend is a lightweight Python server using the FastAPI framework. Its sole purpose is to act as a proxy to fetch YouTube video transcripts, mitigating CORS issues that would arise from direct browser requests. It is deployed as a Vercel Serverless Function.

Sources: api/index.py

API Endpoint

The backend exposes a single GET endpoint.

Method	Path	Description -
GET	/api/transcript	Fetches the transcript for a given YouTube videoId. It uses the youtube_transcript_api library. -

Sources: api/index.py:80-104

Security and Middleware

The API implements several security measures through FastAPI middleware:

1. Strict CORS: Only allows requests from configured origins (http://localhost:3000, http://localhost:5173 by default).
2. Rate Limiting: Limits requests to /api/transcript to 15 requests per 60 seconds per client IP.
3. Security Headers: Adds X-Content-Type-Options, X-Frame-Options, and Strict-Transport-Security headers to all responses.

Sources: api/index.py:12-51

AI Services Integration

All AI-powered features are handled by the geminiService.ts module, which communicates directly with the Google Gemini API from the client-side.

AI Generation Functions

The service provides several functions, each tailored for a specific content generation task using a unique system instruction.

Function Name	Description -
cleanTranscriptText	Cleans a raw transcript snippet into a concise, grammatically correct sentence. Used for "margin notes". -
generateTwitterThread	Converts a full transcript into a 7-10 tweet thread, formatted as a numbered list. -
generateLinkedInPost	Converts a transcript into a JSON object containing a hook, body, CTA, and hashtags for a LinkedIn post. -
generateBlogOutline	Converts a transcript into a JSON object representing a blog post outline with a title, sections, and SEO keywords. -
generateKeyTakeaways	Extracts 5-7 key takeaways from a transcript, returning a JSON array of objects with an emoji and text. -

Sources: services/geminiService.ts

AI Interaction Flow (Margin Note Creation)

This sequence diagram details the process of a user selecting transcript text to generate a "margin note".