Getting Started

Relevant source files

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

• README.md
• package.json
• api/index.py
• services/geminiService.ts
• components/Header.tsx
• App.tsx
• hooks/useContentGenerator.ts

This guide provides instructions for setting up and running the Nota application locally. Nota is a "Random Access Intelligence" engine designed to transform long-form YouTube content into actionable summaries and content formats. It combines a React frontend with a Python FastAPI backend to fetch video transcripts and generate AI-powered notes and content using the Google Gemini API.

The core architecture involves a user interface for video playback and transcript interaction, a backend service to proxy requests for YouTube transcripts, and a set of services on the frontend to interact with the Gemini API for content generation.

Sources: README.md:4-12, App.tsx

Architecture Overview

The application is composed of a frontend single-page application (SPA) and a backend API. The frontend is built with React and Vite, while the backend is a Python server using FastAPI.

This diagram illustrates the high-level interaction between the system components.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Prerequisite	Requirement	Description
Node.js	v18+	Required to run the frontend development server and install dependencies.
Gemini API Key	string	Required for all AI-powered features, including margin notes and content generation.

Sources: README.md:41-42

Installation and Configuration

Follow these steps to get your development environment set up.

1. Clone & Install Dependencies

First, clone the repository and install the required Node.js packages.

git clone https://github.com/rznies/youtube_notes.git
cd youtube_notes
npm install

This command reads the dependencies and devDependencies from package.json and installs them into the node_modules directory.

Sources: README.md:45-48, package.json:16-39

2. Configure Environment Variables

The application requires environment variables for both the frontend and backend.

Frontend Configuration

The frontend requires a Google Gemini API key. Create a .env.local file in the root of the project and add your key.

VITE_GEMINI_API_KEY=your_api_key_here

This key is accessed in the application via import.meta.env.VITE_GEMINI_API_KEY and can also be configured through the settings modal in the UI. The application includes a feature to validate the key by making a test call to the Gemini API.

Sources: README.md:50-53, components/Header.tsx:138-145, services/geminiService.ts:60-70

Backend Configuration

The Python backend can be configured with the following optional environment variables to manage rate-limiting, CORS, and proxy settings.

Variable	Default Value	Description
RATE_LIMIT_REQUESTS	15	The number of allowed requests to /api/transcript per window.
RATE_LIMIT_WINDOW	60	The time window in seconds for rate limiting.
ALLOWED_ORIGINS	http://localhost:3000,http://localhost:5173	Comma-separated list of origins allowed to make requests.
WEBSHARE_USER	None	Username for the Webshare proxy to fetch transcripts.
WEBSHARE_PASS	None	Password for the Webshare proxy.

Sources: api/index.py:9-13, api/index.py:65-76

Running the Application

The project uses concurrently to run the frontend and backend servers with a single command.

npm run dev

This command executes two scripts in parallel as defined in package.json:

1. npm run dev:backend: Starts the FastAPI server on port 3001 using uvicorn.
2. npm run dev:frontend: Starts the Vite development server, typically on port 5173.

Sources: package.json:6-8

The following diagram shows the startup flow initiated by npm run dev.

Available Scripts

The package.json file defines several scripts for development, testing, and building.

Script	Description
dev	Runs the backend and frontend development servers concurrently.
dev:backend	Runs the Python FastAPI backend with auto-reloading on port 3001.
dev:frontend	Runs the Vite frontend development server.
build	Builds the frontend application for production using Vite.
vercel-build	An alias for build, specifically for Vercel deployments.
preview	Serves the production build locally.
test	Runs frontend tests using Vitest.
test:python	Runs backend tests using Pytest.
test:all	Runs both frontend and backend tests.

Sources: package.json:5-14

API Key Setup Flow

The Gemini API key is essential for AI features. The user can enter it via a settings modal in the application's header.

This sequence diagram shows how the API key is validated and saved.