YouLearnTube

Turn a learning goal and selected YouTube playlists into a spoiler-safe, adaptive study workspace.

YouLearnTube turns scattered YouTube tutorials into one guided course. A learner writes a goal in plain language, selects recommended playlists, which then turns them into a structured video path, and receives AI assistance that is based only in the material they have already watched thus avoiding questions or explanations that introduces concept that learner don't understand.

The goal is not to add a chat box on top of YouTube which can already be done by using 'ask question' option. The goal is to make free video learning feel like a focused learning product: a course with a sequence, watched-time awareness, source-linked explanations, progressive concepts, easing learners to note taking, checks for understanding, and a recommendation for what to do next.

Contents

• What the learner experiences
• Why YouLearnTube is different
• End-to-end architecture
• Spoiler-safe learning boundary
• Learning loop and adaptive path
• AI, transcript, and embedding design
• Frontend experience
• Repository map
• API surface
• Run locally
• Providers, mock mode, and cost control
• Deployment profile
• How Codex helped build YouLearnTube
• Demo flow
• Current boundaries and next steps

What the learner experiences

1. Describe a learning goal. A learner can write a request such as Learn Redis caching, but skip the basics. The model is used only to extract structured intent such as topic, level, exclusions, and search queries.
2. Choose source playlists. The backend, not the model, makes the YouTube Data API calls. The learner sees ranked playlist choices and selects the ones that they prefer in the course.
3. Receive one clean course. The selected playlists are merged, video metadata is normalised, exact and semantic duplicates are removed deterministically, and the learner gets one ordered syllabus with total, watched, and remaining duration avoiding users to go through a the introductions and realizing that the topic is same as the previous viewed video.
4. Start watching immediately. The active YouTube video is usable while its transcript is requested, timestamped, chunked, embedded, and indexed in the background. The app does not make the learner wait for every course transcript before opening the player. This allows faster execution thanks to only sending some part of whole transcript to be processed.
5. Learn only from watched material. The tutor, mind map, flashcards, quiz, and adaptive recommendation respect the learner's server-side watch position. Future lesson evidence is excluded at retrieval time rather than merely hidden in the browser. Mind-Map is used to allow users to see the important concepts and how they connect with one another in the video, flashcards helps by finding the concept and allowing user to get them as notes form.
6. Understand concepts, not creator metadata. A shared instructional-content filter removes greetings, channel introductions, sponsor reads, calls to subscribe, and similar low-value material before maps, quizzes, and cards are generated.
7. Reflect and continue. After an eligible lesson, the learner may attempt or explicitly skip its learning check. Every fifth lesson becomes a recap checkpoint. Concept understanding, quiz results, tutor feedback, and focus behavior feed an explainable next recommendation.

The product journey

flowchart LR
    A["Learner writes a goal"] --> B["Intent extraction<br/>(topic, level, exclusions, search queries)"]
    B --> C["FastAPI validates the contract"]
    C --> D["YouTube Data API<br/>playlist search and ranking"]
    D --> E["Learner selects playlists"]
    E --> F["Playlist merge + metadata enrichment"]
    F --> G["Deterministic exact and semantic deduplication"]
    G --> H["Temporary course session<br/>ordered video syllabus"]
    H --> I["React learning workspace"]
    I --> J["Watch, ask, map, review, and adapt"]

    classDef learner fill:#ede9fe,stroke:#7c3aed,color:#312e81
    classDef backend fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef service fill:#ecfdf5,stroke:#059669,color:#064e3b
    class A,E,I,J learner
    class B,C,F,G,H backend
    class D service

Why YouLearnTube is different

Design choice	What it means in practice	Why it matters
Backend-owned discovery	The model returns a validated intent object. FastAPI calls YouTube and decides how results are ranked.	A language model cannot make uncontrolled YouTube requests or invent playlist results.
Deterministic deduplication	Embeddings represent title + description; cosine similarity finds likely duplicates; quality metrics select the retained video.	Similarity is measurable and reproducible. The LLM is never asked to guess whether two videos are duplicates.
Lazy transcript ingestion	Only the active lesson is transcribed and indexed when it is needed.	The player remains responsive, cost is controlled, and transcript failures affect one lesson rather than an entire course.
Server-enforced spoiler safety	The server clamps the client timestamp to saved progress and retrieves only chunks ending before that safe position.	Changing a browser value cannot reveal future transcript evidence or future map nodes.
Topic-first generation	Shared filtering selects substantive teaching chunks before map, quiz, and flashcard generation.	Learners study React, Redis, caching, or another actual topic - not a creator's intro or channel promotion.
Explainable adaptation	The recommendation is based on visible concept states, quizzes, tutor feedback, and focus sessions.	The app can say whether the next action is to review, continue, retry a weak concept, or take a break.
Provider independence	Generation and embedding providers are configured separately and have deterministic mock paths.	The project can demo without credits, switch providers, or run local embeddings without changing product behavior.

End-to-end architecture

System overview

flowchart TB
    UI["React + Vite workspace"]
    API["FastAPI API<br/>validation, policy, orchestration"]
    YouTube["YouTube Data API v3"]
    Captions["youtube-transcript-api<br/>or Supadata native captions"]
    Providers["OpenAI / Gemini / Anthropic<br/>compatible local endpoint / mock"]
    Embeddings["OpenAI / Gemini / FastEmbed\nor deterministic mock"]
    Store["Temporary course JSON store"]
    Chroma["ChromaDB<br/>timestamped transcript chunks"]

    UI -->|"goal, playlist selection, progress, questions"| API
    API --> YouTube
    API --> Captions
    API --> Providers
    API --> Embeddings
    API <--> Store
    API <--> Chroma
    Captions --> API
    Embeddings --> Chroma
    Chroma --> API
    API -->|"courses, evidence, maps, quizzes, cards, recommendations"| UI

    classDef app fill:#ede9fe,stroke:#7c3aed,color:#312e81
    classDef backend fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef external fill:#fff7ed,stroke:#ea580c,color:#7c2d12
    classDef data fill:#ecfdf5,stroke:#059669,color:#064e3b
    class UI app
    class API backend
    class YouTube,Captions,Providers,Embeddings external
    class Store,Chroma data

Discovery and course creation

The discovery model has a deliberately narrow responsibility. It turns natural language into a typed shape, for example:

{
  "topic": "Redis caching",
  "level": "intermediate",
  "exclude": ["basic installation"],
  "search_queries": [
    "Redis caching tutorial intermediate",
    "Redis cache patterns course"
  ]
}

FastAPI validates that output with Pydantic, then youtube_service.py owns the actual search.list, playlist-item, and video-metadata work. This boundary keeps external API permissions, ranking, error handling, and mock behavior in normal application code rather than a prompt.

When playlists are selected, the ingestion services:

1. collect playlist items and video IDs;
2. fetch title, description, thumbnail, duration, channel, view, and like metadata;
3. preserve source playlist IDs for each video;
4. normalise video records into one course shape;
5. remove exact duplicates;
6. embed title and description text for semantic comparison;
7. apply the configured cosine-similarity threshold;
8. retain the higher-quality video when content is materially duplicated; and
9. return the complete ordered video list to React, not just a count.

The frontend can therefore render the course as soon as ingestion returns. It does not need a second metadata request before it can show the syllabus, duration totals, thumbnails, and active lesson.

Course, transcript, and retrieval state

State	Current owner	Key data	Lifetime in the anonymous demo profile
Course and video syllabus	course_store.py	selected playlists, videos, duration totals, progression, map, cards, quizzes, feedback, focus sessions	Local development: disk. Cloud Run: temporary /tmp data on one instance.
Transcript chunks	chroma_service.py	course ID, video ID, playlist IDs, title, start time, end time, chunk text, embedding profile	Same temporary lifecycle as the course.
Browser UI state	React hooks and components	active tab, picture-in-picture state, modal state, current player view	Browser session; restored from backend course state where relevant.
Provider configuration	backend/.env or deployment secrets	API keys, provider models, embedding provider, timeout and demo flags	Server-only. Never exposed as VITE_ values.

Spoiler-safe learning boundary

Spoiler safety is a data-access rule, not a styling rule.

The browser reports a timestamp, but that timestamp is treated as a request rather than a source of truth. Before tutor retrieval or progressive-map visibility is calculated, the backend reads the saved course progression and chooses the safe timestamp. The answer context is built only from chunks whose end time is at or before that safe point.

sequenceDiagram
    participant L as Learner / browser
    participant P as Progression store
    participant A as FastAPI tutor endpoint
    participant C as Chroma transcript chunks
    participant G as Generation provider or mock

    L->>A: Question + browser playback timestamp
    A->>P: Read saved watch position
    P-->>A: Server-side watch position
    A->>A: safe_time = min(requested time, saved progress)
    A->>C: Retrieve chunks ending at or before safe_time
    C-->>A: Watched instructional evidence only
    A->>G: Evidence packet + response rules
    G-->>A: Grounded answer and related concept IDs
    A-->>L: Answer, source timestamps, visible-map highlights

    Note over A,C: Future chunks are never put in the evidence packet.
    Note over A,L: A forged browser timestamp cannot unlock future content.

The same rule powers several features:

• Tutor: retrieves watched-only chunks and returns source timestamps that can seek the player.
• Mind map: only returns concept nodes whose source time is visible at the learner's progress.
• Flashcards: unlock after valid lesson completion and use topic-focused lesson evidence.
• Quiz: draws from the current completed lesson, or the last five eligible lessons for a recap.
• Adaptive learning: only reasons from already visible concepts and recorded learner activity.

Why both client and server progress matter

The player UI tracks the live position so watched and remaining time feel immediate. The backend stores validated progression so learning tools are reliable across tool tabs, UI transitions, and browser refreshes. The client is responsible for responsiveness; the backend is responsible for learning policy.

Learning loop and adaptive path

Lesson progression

flowchart TD
    A["Open next unlocked lesson"] --> B["Watch video<br/>progress reported to backend"]
    B --> C{"Reached valid completion threshold?"}
    C -->|"No"| B
    C -->|"Yes"| D["Mark lesson complete"]
    D --> E["Unlock lesson quiz or recap checkpoint"]
    E --> F{"Learner choice"}
    F -->|"Attempt"| G["Submit answers<br/>record results and explanations"]
    F -->|"Skip learning check"| H["Record deliberate skip"]
    G --> I["Unlock concept cards + visible map state"]
    H --> I
    I --> J["Compute explainable next recommendation"]
    J --> K["Continue, review, retry, or take a focus break"]

    classDef action fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef gate fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef outcome fill:#ecfdf5,stroke:#059669,color:#064e3b
    class A,B,D,E,G,H,I,J,K action
    class C,F gate

The product intentionally distinguishes skipping a lesson from skipping a quiz:

• A skipped lesson unlocks the next video for course navigation but remains replayable.
• Skipping a lesson does not falsely generate that lesson's maps, flashcards, or quiz assets as though the learner had studied it.
• After a genuinely completed lesson, the learner can either attempt the quiz or consciously skip the learning check.
• The fifth eligible checkpoint is a recap quiz, replacing the ordinary single-lesson quiz for that position.

Adaptive recommendation

The adaptive path is not a hidden black-box score. It combines explicit inputs that the learner can understand:

• concept status chosen from the map, such as review, learning, or understood;
• quiz outcome and explanations;
• tutor feedback;
• completed, skipped, and currently available videos;
• learner focus-session behavior; and
• current course order and remaining duration.

flowchart LR
    A["Visible concept states"] --> E["Adaptive learning service"]
    B["Quiz outcomes"] --> E
    C["Tutor feedback"] --> E
    D["Focus-session signals"] --> E
    E --> F["Explainable recommendation"]
    F --> G["Recommended next concept"]
    F --> H["Review / continue / retry action"]
    F --> I["Suggested focus and break duration"]
    G --> J["Map node colour and learning path"]

    classDef input fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef engine fill:#ede9fe,stroke:#7c3aed,color:#312e81
    classDef output fill:#ecfdf5,stroke:#059669,color:#064e3b
    class A,B,C,D input
    class E engine
    class F,G,H,I,J output

Progressive mind map

The map is a learning surface, not a generic course diagram. It uses React Flow and supports bounded pan and zoom, source-time jumps, tutor highlights, understanding actions, and state colours. Nodes are constrained to the real learning path:

• a concept is absent until its source is safe to show;
• the current concept can be highlighted while the learner watches;
• tutor answers can highlight related visible nodes;
• each node offers a source action that seeks the video to the supporting moment; and
• node state can feed the adaptive recommendation.

When Map, Quiz, or Cards becomes the main stage, the player becomes a compact picture-in-picture frame and keeps playing if the video has not ended. Returning to Video restores the original workspace layout.

AI, transcript, and embedding design

Lazy transcript ingestion

flowchart LR
    A["Learner opens a video"] --> B["Player is ready immediately"]
    A --> C["Request transcript in background"]
    C --> D{"Captions available?"}
    D -->|"Yes"| E["Preserve text + start/end timestamps + language diagnostics"]
    E --> F["Select instructional material"]
    F --> G["Chunk into small timestamped blocks"]
    G --> H["Create embeddings"]
    H --> I["Index in Chroma by course and video"]
    I --> J["Tutor and map can use watched evidence"]
    D -->|"No or restricted"| K["Keep player usable<br/>show safe non-technical state<br/>use fallback when configured"]

    classDef action fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef decision fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef data fill:#ecfdf5,stroke:#059669,color:#064e3b
    class A,B,C,E,F,G,H action
    class D decision
    class I,J,K data

Transcript ingestion retains useful diagnostic information - status, failure class, reason, selected language, chunk count, and embedding count - for the developer-facing diagnostic flow. The learner-facing UI avoids raw provider stack traces. A transcript problem should not prevent the video itself from being watched.

Multilingual source, English learning output

Source transcript chunks retain their original language and timestamps so evidence remains faithful to the video. The learning-generation pipeline can produce English map labels, tutor explanations, quiz questions, flashcards, and concept summaries while preserving the source context and timestamps. This avoids a map with mixed-language labels while still grounding the result in the original video.

Quality gate for generated learning assets

instructional_content_service.py is shared by the map, quiz, and flashcard workflows. It prioritises chunks that contain substantive teaching and rejects low-value source material such as:

• creator greetings and introductions;
• channel or instructor biography;
• sponsor messages and promotions;
• calls to subscribe, like, or comment;
• generic course housekeeping; and
• unrelated conversational filler.

The result can be a small map, a small flashcard deck, or even a single excellent question when that is the only meaningful learning value in a lesson. Quantity is deliberately not treated as quality.

Provider separation

Generation and embeddings are separate decisions. A text-generation model does not have to be the embedding model.

Capability	Supported choices	Purpose
Intent, tutor, quiz, map, flashcard generation	OpenAI, Gemini, Anthropic, OpenAI-compatible local endpoint, deterministic mock	Structured or evidence-grounded learning text.
Retrieval embeddings	OpenAI embeddings, Gemini embedding model, local FastEmbed ONNX model, deterministic mock	Semantic deduplication and Chroma retrieval vectors.
Transcript retrieval	youtube-transcript-api, optional Supadata native-caption fallback, mock transcript data	Timestamped text for the active video.
YouTube discovery	YouTube Data API v3 or deterministic mock catalog	Playlist and video metadata.

gemini-embedding-001 is used for Gemini embeddings. Gemini Flash and Flash-Lite are generation models; they are not the embedding provider.

Frontend experience

The React workspace is built around three learning zones:

1. Course path: the syllabus, video status, total course duration, watched time, remaining time, and progression choices.
2. Video stage: the YouTube player and controls for completion, skip, seek, focus, and safe progress synchronisation.
3. Learning workspace: Tutor, Map, Cards, and Check tabs. One learning tool can expand into the main stage while the video stays available in picture-in-picture.

Key UX details

• Live watched and remaining duration update from player progress; learners do not need to click a time badge or refresh the page.
• Player controls fade while watching and return on hover, matching familiar video behavior.
• The Focus timer can pause the video for a break and show a break countdown modal.
• The learner may complete or skip lessons honestly; the application does not pretend that a skipped lesson was studied.
• The Demo control is environment-gated and can stage a complete active lesson for a private hackathon pitch. It is not intended as a public learner shortcut.
• A feature guide and project-tour modal explain the product to a new judge without requiring them to discover every interaction themselves.
• An error boundary prevents one UI render error from turning the whole learning dashboard white.

Live workspace versus browser-only mock

The visual prototype and the production workspace share the same component language. The browser-only mock is intentionally isolated under frontend/src/mock/ so design experiments can be performed without FastAPI, keys, transcripts, or network requests. The live app uses frontend/src/services/api.js and the real backend contracts.

Mode	How to start it	Use it for
Live workspace	npm run dev with FastAPI running	End-to-end discovery, ingestion, transcript, and learning-tool integration.
Browser mock	npm run dev:mock	Fast UI iteration and a dependency-free visual demonstration.

See frontend/src/mock/README.md for the mock's scope.

Repository map

AiProf/
|
|-- frontend/
|   |-- src/
|   |   |-- App.jsx                    Discovery and course-entry state
|   |   |-- components/                Player, syllabus, tutor, map, cards, quiz, demo, guide
|   |   |-- hooks/                     Progress, transcript, focus, adaptive learning synchronisation
|   |   |-- services/api.js            Single live HTTP client and payload mapping
|   |   `-- mock/                      Browser-only UI fixture
|   `-- vite.config.js
|
|-- backend/
|   |-- app/
|   |   |-- main.py                    FastAPI setup, CORS, routers
|   |   |-- config.py                  Provider, storage, timeout, and demo settings
|   |   |-- routers/                   Thin HTTP contracts by feature
|   |   |-- services/                  Discovery, ingestion, transcripts, RAG, maps, quizzes, cards, adaptation
|   |   |-- models/                    Persisted learning-domain models
|   |   |-- mock/                      Deterministic external-service fallbacks
|   |   `-- schemas.py                 Pydantic request and response contracts
|   |-- Dockerfile
|   `-- requirements.txt
|
|-- README.md                          This product and architecture guide
|-- PROJECT_CODE_GUIDE.md              File-by-file implementation guide
|-- DEPLOYMENT.md                      Cloud Run and static-host deployment guide
`-- PITCH.md                           Three-minute product and Codex story

Backend ownership by concern

Concern	Primary files	Responsibility
App and configuration	main.py, config.py, dependencies.py, schemas.py	CORS, settings, API contracts, health, provider selection.
Discovery	routers/discovery.py, openai_service.py, gemini_service.py, youtube_service.py	Intent extraction, validation, playlist search, ranking, mock fallback.
Course ingestion	routers/ingestion.py, ingestion_service.py, playlist_ingestion_service.py, video_metadata_service.py, deduplication_service.py	Playlist merge, metadata enrichment, quality comparison, course creation.
Transcripts and vectors	transcript_service.py, video_transcript_service.py, chunking_service.py, embedding_service.py, chroma_service.py	Timestamped transcript retrieval, chunking, vector creation, course-scoped index.
Tutor	routers/tutor.py, tutor_context_service.py, tutor_generation_service.py, tutor_feedback_service.py	Watch-position clamp, evidence packet, direct/Socratic answer, source receipts, feedback.
Mind map	routers/mindmap.py, mindmap_service.py, mindmap_generation_service.py	Concept graph creation, instructional filtering, watched-only visibility.
Retention checks	routers/quiz.py, quiz_context_service.py, quiz_generation_service.py, routers/flashcards.py, flashcard_*_service.py	Topic-focused quiz/cards, validation, regeneration when old low-value content is detected.
Progress and adaptation	routers/progression.py, progression_service.py, adaptive_learning_service.py, presentation_demo_service.py	Lesson availability, complete/skip semantics, quiz gates, concept state, focus sessions, pitch control.
Temporary state	course_store.py, models/	Anonymous course state, progression, maps, cards, quiz results, feedback, and eviction.

For a deeper file-by-file walkthrough, read PROJECT_CODE_GUIDE.md.

API surface

The main client-facing routes are listed below. FastAPI also exposes interactive documentation locally at /docs.

Route	Purpose	Important behavior
GET /health	Deployment health check	Reports whether course storage is local or ephemeral.
POST /api/discovery	Turn a goal into playlist choices	Validates structured intent, then calls YouTube or mock data.
POST /api/ingestion	Build a course from playlist IDs	Returns course summary, deduplicated video metadata, and initial progression.
POST /api/courses/{course_id}/videos/{video_id}/transcript	Prepare the active lesson's transcript	Runs lazily and returns language/status/chunk diagnostics without blocking playback.
POST /api/tutor/chat	Ask a watched-only question	Clamps timestamp, returns evidence-linked answer and related visible concept IDs.
POST /api/tutor/feedback	Record response feedback	Lets adaptation use helpfulness signals without storing a full chat history.
GET /api/courses/{course_id}/mind-map	Load current visible map	Sends only watched, instructional concepts.
GET /api/flashcards/{course_id}/videos/{video_id}	Load lesson cards	Requires valid lesson completion and regenerates stale low-value cards.
GET /api/quizzes/{course_id}/current	Load lesson or recap quiz	Enforces current eligibility and evidence-grounded questions.
POST /api/progression/{course_id}/videos/{video_id}/watch-position	Save validated watching progress	Supports reliable watched and remaining time.
POST /api/progression/{course_id}/videos/{video_id}/complete	Complete a lesson	Unlocks the appropriate learning check.
POST /api/progression/{course_id}/videos/{video_id}/skip	Skip a lesson	Unlocks navigation while keeping the lesson replayable and unstudied.
POST /api/progression/{course_id}/quizzes/{quiz_id}/complete	Submit learning check	Stores outcomes used by adaptation.
POST /api/progression/{course_id}/quizzes/{quiz_id}/skip	Skip learning check	Records an explicit learner choice.
GET /api/courses/{course_id}/learner-progress	Load adaptation state	Returns concept progress, focus state, and the current recommendation.
PUT /api/courses/{course_id}/concepts/{concept_id}/status	Update map understanding state	Recomputes the recommendation immediately.
POST /api/courses/{course_id}/focus-sessions	Start an adaptive focus session	Records planned work and break intervals.

The presentation route is intentionally omitted from normal product documentation because it returns 404 unless ENABLE_PRESENTATION_DEMO=true.

Run locally

Prerequisites

• Python 3.11 or newer is recommended.
• Node.js 20 or newer is recommended.
• A YouTube Data API key is needed only for live YouTube discovery.
• Provider keys are optional when using mock mode or local embeddings.

Backend

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn app.main:app --reload --port 8000

The API runs at http://localhost:8000. Check http://localhost:8000/health and inspect http://localhost:8000/docs during development.

Frontend

cd frontend
npm install
Copy-Item .env.example .env
npm run dev

Open http://localhost:5173.

For local development, the backend allows both http://localhost:5173 and http://127.0.0.1:5173 through CORS. Use FRONTEND_ORIGIN for the exact deployed frontend origin in production.

Environment variables

Keep all secret keys in backend/.env or managed deployment secrets. Do not put provider keys in variables starting with VITE_.

# backend/.env - useful offline/demo baseline
MOCK_MODE=true
LLM_PROVIDER=mock
EMBEDDING_PROVIDER=mock

# frontend/.env - live local API
VITE_API_BASE_URL=http://localhost:8000
VITE_API_MODE=live

See backend/.env.example and frontend/.env.example for the complete settings list.

Providers, mock mode, and cost control

Reliable no-credit baseline

MOCK_MODE=true
LLM_PROVIDER=mock
EMBEDDING_PROVIDER=mock

This produces deterministic playlist-like results, transcript data, tutor messages, quizzes, cards, maps, and adaptive recommendations. It is useful for UI work, an offline hackathon demo, or verifying a fresh clone without paid API credits.

Hosted and local options

Setting	Choices	Notes
LLM_PROVIDER	mock, auto, openai, gemini, anthropic	Controls text generation. auto tries configured providers according to the fallback configuration.
OPENAI_BASE_URL	Optional compatible endpoint	Enables an OpenAI-compatible local or self-hosted generation endpoint.
EMBEDDING_PROVIDER	mock, openai, gemini, local	Independent from text generation.
EMBEDDING_PROVIDER=local	FastEmbed multilingual MiniLM ONNX model	CPU-friendly, no hosted embedding quota, and suitable for multilingual source material.
EMBEDDING_PROVIDER=gemini	gemini-embedding-001	Dedicated Gemini vector model with batching/rate-limit behavior handled by the provider service.
SUPADATA_TRANSCRIPT_MODE=native	Existing captions only	Optional hosted fallback when direct caption requests are restricted in a cloud environment.

Cost-control decisions already in the architecture

• The app embeds only the active video when it is opened, not every video in every selected playlist.
• Retrieval uses the most relevant small chunks instead of sending a whole transcript to a generation model.
• Transcript chunks keep timestamps and metadata so one local vector lookup can serve tutor, map, quiz, card, and recommendation contexts.
• Local FastEmbed can remove hosted embedding charges entirely for a small demo deployment.
• Deterministic mock providers let the full experience work when credits, quota, captions, or a hosted model are unavailable.
• Embedding profiles use isolated Chroma collections, preventing vectors from incompatible dimensions from being mixed.

Deployment profile

What can be deployed now

The current deployment target is an anonymous, temporary-session hackathon app:

• Frontend: Vite static build deployed to Vercel or another static host.
• Backend: FastAPI container from backend/Dockerfile deployed to Cloud Run.
• Embeddings: local FastEmbed can run inside the Cloud Run container, avoiding a hosted embedding dependency.
• State: course JSON and Chroma vectors are local to one backend instance.

flowchart LR
    B["Browser<br/>Vercel or static host"] -->|"HTTPS API calls"| R["Cloud Run<br/>FastAPI + FastEmbed"]
    R --> Y["YouTube / caption services"]
    R --> L["Optional text-generation provider"]
    R --> T["Temporary /tmp course store<br/>and Chroma index"]

    classDef public fill:#ede9fe,stroke:#7c3aed,color:#312e81
    classDef server fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    classDef external fill:#fff7ed,stroke:#ea580c,color:#7c2d12
    classDef temp fill:#fef3c7,stroke:#d97706,color:#78350f
    class B public
    class R server
    class Y,L external
    class T temp

Cloud Run has a writable but temporary filesystem. The Docker configuration stores anonymous course JSON and Chroma data under /tmp/youlearn-tube, expires inactive courses after four hours, and caps the number of warm-instance courses. Set Cloud Run to one maximum instance for this profile because the current state stores are instance-local.

A container restart intentionally starts with a clean course store. This is acceptable for an anonymous pitch or short learning session and avoids exposing one anonymous visitor's temporary state to another. It is not persistent-account infrastructure.

Read DEPLOYMENT.md before publishing. It contains the expected environment variables, Docker assumptions, Cloud Run limits, CORS configuration, presentation flags, and the full durable-production upgrade path.

Private presentation control

The private demo control exists to make a three-minute judging session practical. When both flags are enabled, it prepares the active lesson's full learning assets without requiring a judge to watch an entire video first.

# frontend build environment
VITE_ENABLE_PRESENTATION_DEMO=true

# backend environment
ENABLE_PRESENTATION_DEMO=true

This should be disabled for a normal public deployment. The project treats it as a presentation feature, not a standard learner path.

How Codex helped build YouLearnTube

Codex was used as a build partner from planning through the final pitch. Its role was not limited to producing isolated code snippets. The collaboration continuously moved between product design, implementation, debugging, verification, documentation, and presentation polish.

Codex collaboration lifecycle

flowchart LR
    A["Vision<br/>AI-assisted YouTube learning"] --> B["Roadmap<br/>Days, hours, priorities"]
    B --> C["Architecture<br/>Custom code vs APIs and models"]
    C --> D["Implementation<br/>FastAPI, React, services, contracts"]
    D --> E["Diagnosis<br/>transcripts, provider quota, UI state, deployment"]
    E --> F["Refinement<br/>spoiler safety, topic quality, adaptive UX"]
    F --> G["Verification<br/>builds, health, mocks, deployment review"]
    G --> H["Handoff<br/>README, code guide, deployment guide, pitch video"]

    classDef phase fill:#ede9fe,stroke:#7c3aed,color:#312e81
    class A,B,C,D,E,F,G,H phase

From hackathon brief to practical scope

The starting brief contained a large number of features: discovery, playlist merging, transcripts, deduplication, vector retrieval, tutor chat, quizzes, maps, flashcards, adaptive learning, Pomodoro support, deployment, and a short pitch. Codex helped translate that into day-by-day and hour-by-hour work, then repeatedly adjusted the plan as product priorities became clearer.

Important planning decisions included:

• build FastAPI and React/Vite custom code rather than rely on a no-code orchestration layer;
• use a model for natural-language intent and evidence-grounded generation, not for direct YouTube calls or duplicate decisions;
• use deterministic cosine similarity plus quality metrics for duplicate selection;
• index only the active video transcript instead of blocking course creation on all transcripts;
• make the progressive map and spoiler-safe tutor the judge-facing core instead of trying to maximise every optional feature;
• create browser-only mocks for every external dependency so design and pitch work can continue without API credits; and
• make a clear distinction between a deployable anonymous demo and durable multi-user production.

Architecture and backend contributions

Codex helped shape and implement the backend boundaries that keep the application understandable:

Area	Codex contribution	Result in the project
Intent extraction	Kept language models limited to a typed intent response and made FastAPI validate it.	The model cannot directly call YouTube or return arbitrary course objects.
YouTube ingestion	Organised playlist search, playlist-item retrieval, video metadata enrichment, source playlist IDs, quality ranking, and normalisation into dedicated services.	The frontend receives a reusable course/video contract instead of a loose collection of API responses.
Duplicate removal	Separated embedding generation from deterministic cosine comparison and quality-based retention.	Duplicate decisions are inspectable and repeatable.
Transcript resilience	Added lazy active-video indexing, caption diagnostics, language handling, mock data, and optional hosted caption fallback.	Videos remain watchable even if captions are delayed, unavailable, or restricted.
Retrieval safety	Added saved-progress clamping, timestamp-preserving chunks, watched-only retrieval, source receipts, and map visibility filtering.	Tutor and map cannot leak future lesson content through a client-side timestamp.
Provider abstraction	Kept text generation, embeddings, transcript retrieval, and YouTube discovery independently configurable.	A quota or endpoint problem can fall back without turning the full app unusable.
Deployment review	Reviewed CORS, Docker paths, Cloud Run's temporary filesystem, instance-local Chroma, TTL eviction, and one-instance limits.	The deployment documentation describes actual behavior instead of claiming persistence that does not exist.

Learning-design and UX contributions

Codex also helped implement the product details that turn a collection of AI endpoints into a learning experience:

Area	Codex contribution	Learner and judge outcome
Topic quality	Introduced shared instructional-content filtering and regeneration rules for weak cards or quizzes.	Learning assets focus on the real topic rather than presenter intros or promotions.
Tutor modes	Connected direct and Socratic behavior to the same evidence packet and visible map concepts.	A learner can request an answer or be guided toward it without losing grounding.
Mind map	Planned progressive node reveal, source actions, understanding states, tutor highlights, bounded navigation, and picture-in-picture playback.	The map feels like a learning path linked to the actual video, not decoration.
Quiz and cards	Structured per-lesson checks, fifth-lesson recap logic, related distractors, explanations, topic-focused decks, and learner choice to attempt or skip.	Retention features are useful without falsely treating skipped content as learned.
Adaptive path	Joined quiz outcomes, map states, tutor feedback, course order, and focus sessions into explicit recommendations.	The application can explain what the learner should do next and why.
Watch flow	Improved live watched/remaining time, honest complete/skip semantics, replayability, and no-manual-reload state updates.	The course behaves like a guided product rather than a static playlist.
Demonstration UX	Added the feature guide, presenter controls, environment gating, responsive workspace transitions, and safe fallback states.	A judge can see the complete product story within a short demo.

Debugging and verification contributions

The build involved iterative troubleshooting, not a single happy path. Codex helped identify and address issues such as:

• transcript requests blocked despite captions being visible in the YouTube UI;
• external embedding quotas and 429 rate-limit responses;
• missing or invalid hosted model endpoints;
• frontend loading states that waited unnecessarily for background transcript work;
• static watch-time UI that did not reflect live player progress;
• stale polling behavior that would be wasteful on Cloud Run;
• a blank React screen caused by an unhandled view transition;
• language consistency in generated maps, cards, quizzes, and tutor output;
• learning assets incorrectly drawing attention to instructor introductions rather than instructional material; and
• deployment assumptions around local Chroma, Cloud Run restarts, and CORS.

The final review process also covered frontend/backend connectivity, mock coverage, local models, Docker configuration, production build behavior, health checks, README and deployment documentation, and pitch preparation.

Codex and the final pitch

Codex also helped produce the presentation material: it updated PITCH.md, generated architecture-flow visuals, aligned the product recording to the narration, created subtitles, and assembled the narrated diagram-led demonstration video. The closing line of the pitch explicitly acknowledges that Codex generated the video as part of this build workflow.

This is intentionally documented because the project is an example of using Codex across the whole engineering loop: planning a vision, implementing it, testing it, explaining it, and preparing a clear handoff.

Demo flow

For a three-minute judge demonstration, keep the walkthrough focused on the learning story rather than every endpoint.

1. Enter a goal such as Learn Redis caching, skip the basics.
2. Show that discovery produces playlist choices from validated intent rather than a model directly controlling YouTube.
3. Select playlists and show the merged course with total and remaining duration.
4. Open a video. Explain that playback starts immediately while the active transcript is indexed in the background.
5. Open the map and show a visible concept with source action and understanding state.
6. Ask the tutor a question. Show the evidence timestamp and related map highlights.
7. Complete the lesson or use the private presentation control. Open the learning check, flashcards, and adaptive recommendation.
8. Show the focus control and explain that recommendations and focus duration adapt to recorded learning signals.
9. Finish with the spoiler-safety diagram and the Codex collaboration story.

The complete narration and timing are in PITCH.md.

Suggested verification before a demo or deployment

# Backend syntax/import check
cd backend
.\.venv\Scripts\python.exe -m compileall app

# Start the API, then confirm health
uvicorn app.main:app --port 8000
# In a second terminal:
Invoke-RestMethod http://localhost:8000/health

# Frontend lint and production build
cd ..\frontend
npm run lint
npm run build

Then verify one full learning path manually:

• discover and ingest a course;
• open a video while transcript indexing is still pending;
• confirm live watched and remaining time change;
• ask a tutor question before and after a meaningful timestamp;
• verify the map does not reveal future nodes;
• complete a lesson and open its quiz/cards;
• skip a lesson and confirm it stays replayable but unstudied;
• check an adaptive recommendation and focus timer update; and
• repeat the flow in mock mode with no external API keys.

Current boundaries and next steps

YouLearnTube is ready as an anonymous, temporary-session hackathon application. It intentionally does not claim to be a durable multi-user learning platform yet.

Before offering accounts or long-lived courses, the project needs:

1. authentication and per-user/course authorisation;
2. a shared database for course, progression, quiz, map, feedback, and focus state;
3. a shared vector store for transcript embeddings;
4. a job queue for transcript indexing and asset generation;
5. provider and request rate limits, abuse controls, observability, backups, and a privacy/retention policy;
6. multi-instance Cloud Run only after shared state is introduced; and
7. a review of YouTube and caption-provider terms for the intended public use case.

These are explicit next steps, not hidden limitations. The present architecture is optimised for a convincing, reliable anonymous learning demo: it starts quickly, handles missing external services safely, explains its recommendations, and prevents future-video spoilers at the backend boundary.

Further documentation

• PROJECT_CODE_GUIDE.md - file-by-file explanation of the implementation.
• DEPLOYMENT.md - Cloud Run, Vercel/static hosting, environment variables, and persistence limits.
• PITCH.md - three-minute product and Codex collaboration script.
• frontend/src/mock/README.md - browser-only mock workflow.
• backend/app/mock/README.md - backend mock data behavior.