# CLAUDE.md - YouTube Summarizer

This file provides guidance to Claude Code (claude.ai/code) when working with the YouTube Summarizer project.

## 🚩 CRITICAL: Directory Awareness Protocol

**MANDATORY BEFORE ANY COMMAND**: ALWAYS verify your current working directory before running any command.

```bash
# ALWAYS run this first before ANY command
pwd

# Expected result for YouTube Summarizer:
# /Users/enias/projects/my-ai-projects/apps/youtube-summarizer
```

#### Critical Directory Rules
- **NEVER assume** you're in the correct directory
- **ALWAYS verify** with `pwd` before running commands
- **YouTube Summarizer** requires being in `/Users/enias/projects/my-ai-projects/apps/youtube-summarizer`
- **Backend/Frontend commands** must be run from YouTube Summarizer root
- **Database migrations** and Python scripts will fail if run from wrong directory

#### YouTube Summarizer Directory Verification
```bash
# ❌ WRONG - Running from apps directory
cd /Users/enias/projects/my-ai-projects/apps
python3 main.py  # Will fail - not in youtube-summarizer

# ❌ WRONG - Running from main project
cd /Users/enias/projects/my-ai-projects
python3 main.py  # Will run main AI assistant instead!

# ✅ CORRECT - Always navigate to YouTube Summarizer
cd /Users/enias/projects/my-ai-projects/apps/youtube-summarizer
pwd  # Verify: /Users/enias/projects/my-ai-projects/apps/youtube-summarizer
python3 main.py  # Now runs YouTube Summarizer
```

## CRITICAL: Development Standards

**MANDATORY READING**: Before any code changes, read [AGENTS.md](AGENTS.md) for essential development standards:

- **FILE LENGTH**: All files must be under 300 LOC - modular & single-purpose
- **READING FILES**: Always read files in full before making changes - never be lazy
- **EGO**: Consider multiple approaches like a senior engineer - you are limited as an LLM

**Key Rules from AGENTS.md**:
- 🚨 **300 LOC Limit**: Many files currently break this rule and need refactoring
- 🚨 **Read Before Change**: Find & read ALL relevant files before any modifications  
- 🚨 **Multiple Approaches**: Always consider 2-3 different implementation options

See [AGENTS.md](AGENTS.md) for complete development workflows, testing procedures, and quality standards.

## CRITICAL: Documentation Update Rule

**MANDATORY**: After completing significant coding work, automatically update ALL documentation:

### Documentation Update Protocol
1. **After Feature Implementation** → Update relevant documentation files:
   - **CLAUDE.md** (this file) - Development guidance and protocols
   - **AGENTS.md** - Development standards and workflows  
   - **README.md** - User-facing features and setup instructions
   - **CHANGELOG.md** - Version history and changes
   - **FILE_STRUCTURE.md** - Directory structure and file organization

### When to Update Documentation
- ✅ **After implementing new features** → Update all relevant docs
- ✅ **After fixing significant bugs** → Update troubleshooting guides
- ✅ **After changing architecture** → Update CLAUDE.md, AGENTS.md, FILE_STRUCTURE.md
- ✅ **After adding new tools/scripts** → Update CLAUDE.md, AGENTS.md, README.md
- ✅ **After configuration changes** → Update setup documentation
- ✅ **At end of development sessions** → Comprehensive doc review

### YouTube Summarizer Documentation Files
- **CLAUDE.md** (this file) - Development standards and quick start
- **AGENTS.md** - Development workflows and testing procedures
- **README.md** - User documentation and setup instructions
- **CHANGELOG.md** - Version history and feature releases
- **FILE_STRUCTURE.md** - Project organization and directory structure
- **docs/architecture.md** - Technical architecture details
- **docs/prd.md** - Product requirements and specifications

### Documentation Workflow
```bash
# After completing significant code changes:
# 1. Update relevant documentation files
./scripts/restart-backend.sh    # Test changes work
# 2. Update documentation files
# 3. Commit documentation with code changes
git add CLAUDE.md AGENTS.md README.md CHANGELOG.md FILE_STRUCTURE.md
git commit -m "feat: implement feature X with documentation updates"
```

## Class Library Integration

**IMPORTANT**: This project uses the shared AI Assistant Class Library (`/lib/`) for foundational components. Always check the class library before implementing common functionality.

**Key Library Integrations**:
- **Service Framework**: Backend services extend `BaseService` and `BaseAIService` from `/lib/services/`
- **Repository Pattern**: Data access uses `BaseRepository` and `TimestampedModel` from `/lib/data/`  
- **Error Handling**: Consistent exceptions from `/lib/core/exceptions/`
- **Utilities**: Retry logic, caching, and async helpers from `/lib/utils/`

**Usage Examples**:
```python
from ai_assistant_lib import BaseAIService, with_retry, MemoryCache

# AI service with library base class
class AnthropicSummarizer(BaseAIService):
    # Inherits retry, caching, rate limiting
    pass

# Automatic retry for API calls
@with_retry(max_attempts=3)
async def extract_transcript(video_id: str) -> str:
    pass
```

See [AGENTS.md](AGENTS.md) section "Class Library Integration and Usage" for complete integration patterns and examples.

## Project Overview

An AI-powered web application that automatically extracts, transcribes, and summarizes YouTube videos. The application supports multiple AI models (OpenAI, Anthropic, DeepSeek), provides various export formats, and includes intelligent caching for efficiency.

**Status**: Advanced Feature Development - Core functionality complete, enhanced AI features implemented
- **Epic 1**: Foundation & Core YouTube Integration (✅ Stories 1.1-1.5 Complete)  
- **Epic 2**: AI Summarization Engine (✅ Stories 2.1-2.5 Complete)
- **Epic 3**: User Authentication & Session Management (✅ Stories 3.1-3.5 Complete)
- **Epic 4**: Advanced Intelligence & Developer Platform (✅ Story 4.4 Complete: Custom AI Models & Enhanced Export)
- **Epic 5**: Analytics & Business Intelligence (📋 Stories 5.1-5.4 Ready)

## Quick Start Commands

```bash
# Development Setup
cd apps/youtube-summarizer
docker-compose up             # Start full development environment

# Quick Testing (No Auth Required)
open http://localhost:3002/admin    # Direct admin access - No login needed

# BMad Method Story Management
/BMad:agents:sm               # Activate Scrum Master agent
*draft                        # Create next story
*story-checklist              # Validate story quality

# Development Agent Implementation
/BMad:agents:dev              # Activate Development agent
# Follow story specifications in docs/stories/

# Direct Development (without BMad agents)
source venv/bin/activate      # Activate virtual environment
python backend/main.py        # Run backend (port 8000)
cd frontend && npm run dev    # Run frontend (port 3002)

# Testing (Comprehensive Test Runner)
./run_tests.sh run-unit --fail-fast    # Fast unit tests (229 tests in ~0.2s)
./run_tests.sh run-all --coverage      # Complete test suite with coverage
cd frontend && npm test                 # Frontend tests

# Server Management (CRITICAL for Backend Changes)
./scripts/restart-backend.sh         # Restart backend after code changes
./scripts/restart-frontend.sh        # Restart frontend after dependency changes  
./scripts/restart-both.sh            # Restart full stack

# Git Operations
git add .
git commit -m "feat: implement story 1.2 - URL validation"
git push origin main
```

## Architecture

```
YouTube Summarizer
├── Frontend (React + TypeScript)
│   ├── /admin - No-auth admin interface (TESTING)
│   ├── /dashboard - Protected summarizer interface 
│   ├── /login - Authentication flow
│   └── /batch - Batch processing interface
├── API Layer (FastAPI)
│   ├── /api/summarize - Submit URL for summarization
│   ├── /api/summary/{id} - Retrieve summary
│   └── /api/export/{id} - Export in various formats
├── Service Layer
│   ├── YouTube Service - Transcript extraction
│   ├── AI Service - Summary generation (DeepSeek)
│   └── Cache Service - Performance optimization
└── Data Layer
    ├── SQLite/PostgreSQL - Summary storage
    └── Redis (optional) - Caching layer
```

## Authentication Configuration 🔧

The app uses a **flexible authentication system** that adapts based on environment and configuration.

### Default Development Mode (No Authentication)
- **Access**: All routes accessible without login  
- **URL**: `http://localhost:3002/` (main app)
- **Visual**: Orange "Admin Mode" badges and indicators
- **Features**: Complete functionality without authentication barriers
- **Use Case**: Development, testing, demos

### Production Mode (Authentication Required)
- **Trigger**: Automatic in production or `VITE_FORCE_AUTH_MODE=true`
- **Access**: Login required for all protected routes
- **Flow**: `/login` → `/dashboard` → full app access
- **Security**: JWT-based authentication with user sessions

### Configuration Options
```bash
# Development (default - no auth needed)
# No environment variables needed

# Development with auth enabled  
VITE_FORCE_AUTH_MODE=true

# Production with auth disabled (testing)
VITE_AUTH_DISABLED=true
```

### Route Behavior
- **`/`** - Main app (conditionally protected)
- **`/dashboard`** - Same as `/` (conditionally protected)  
- **`/history`** - Job history (conditionally protected)
- **`/batch`** - Batch processing (conditionally protected)
- **`/login`** - Only visible when auth required
- **`/demo/*`** - Always accessible demos

## Development Workflow - BMad Method

### Story-Driven Development Process

**Current Epic**: Epic 3 - User Authentication & Session Management  
**Current Stories**: 
- ✅ **Epic 1 - Foundation & Core YouTube Integration** (Complete)
  - ✅ Story 1.1: Project Setup and Infrastructure
  - ✅ Story 1.2: YouTube URL Validation and Parsing  
  - ✅ Story 1.3: Transcript Extraction Service (with mocks)
  - ✅ Story 1.4: Basic Web Interface
  - ✅ Story 1.5: Video Download and Storage Service
- ✅ **Epic 2 - AI Summarization Engine** (Complete)
  - ✅ Story 2.1-2.5: All AI pipeline and summarization features
- 🚀 **Epic 3 - User Authentication & Session Management** (Current)
  - ✅ Story 3.1: User Authentication System (Backend Complete)
  - 📝 Story 3.2: Frontend Authentication Integration (Ready for implementation)

### 1. Story Planning (Scrum Master)
```bash
# Activate Scrum Master agent
/BMad:agents:sm
*draft                        # Create next story in sequence
*story-checklist              # Validate story completeness
```

### 2. Story Implementation (Development Agent)
```bash
# Activate Development agent
/BMad:agents:dev
# Review story file: docs/stories/{epic}.{story}.{name}.md
# Follow detailed Dev Notes and architecture references
# Implement all tasks and subtasks as specified
```

### 3. Implementation Locations
Based on architecture and story specifications:
- **Backend API** → `backend/api/`
- **Backend Services** → `backend/services/`
- **Backend Models** → `backend/models/`
- **Frontend Components** → `frontend/src/components/`
- **Frontend Hooks** → `frontend/src/hooks/`
- **Frontend API Client** → `frontend/src/api/`

### 4. Testing Implementation
```bash
# Backend testing (Test Runner - Fast Feedback)
./run_tests.sh run-unit --fail-fast                    # Ultra-fast unit tests (0.2s)
./run_tests.sh run-specific "test_video_service.py"    # Test specific modules  
./run_tests.sh run-integration                         # Integration & API tests
./run_tests.sh run-all --coverage --parallel          # Complete suite with coverage

# Test Discovery & Validation
./run_tests.sh list --category unit                   # See available tests (229 found)
./scripts/validate_test_setup.py                      # Validate test environment

# Frontend testing (Vitest + RTL)
cd frontend && npm test
cd frontend && npm run test:coverage

# Manual testing
docker-compose up             # Full stack
# Visit http://localhost:3000 (frontend)
# Visit http://localhost:8000/docs (API docs)
```

### 5. Story Completion
- Mark all tasks/subtasks complete in story file
- Update story status from "Draft" to "Done"
- Run story validation checklist
- Update epic progress tracking

## Testing & Quality Assurance

### Test Runner System
The project includes a production-ready test runner with **229 discovered unit tests** and intelligent categorization.

```bash
# Fast feedback during development
./run_tests.sh run-unit --fail-fast           # Ultra-fast unit tests (~0.2s)
./run_tests.sh run-all --coverage             # Complete validation
cd frontend && npm test                       # Frontend tests
```

**📖 Complete Testing Guide**: See [TESTING-INSTRUCTIONS.md](TESTING-INSTRUCTIONS.md) for comprehensive testing standards, procedures, and troubleshooting.

## Server Restart Protocol

### CRITICAL: When to Restart Servers

**Backend Restart Required** (`./scripts/restart-backend.sh`):
- ✅ After modifying any Python files in `backend/`
- ✅ After adding new API endpoints or routers
- ✅ After changing Pydantic models or database schemas
- ✅ After modifying environment variables or configuration
- ✅ After installing new Python dependencies
- ✅ After any import/dependency changes

**Frontend Restart Required** (`./scripts/restart-frontend.sh`):
- ✅ After installing new npm packages (`npm install`)
- ✅ After modifying `package.json` or `vite.config.ts`
- ✅ After changing environment variables (`.env.local`)
- ✅ When HMR (Hot Module Replacement) stops working
- ❌ NOT needed for regular React component changes (HMR handles these)

**Full Stack Restart** (`./scripts/restart-both.sh`):
- ✅ When both backend and frontend need restart
- ✅ After major architecture changes
- ✅ When starting fresh development session
- ✅ When debugging cross-service communication issues

### Restart Script Features
```bash
# All scripts include:
- Process cleanup (kills existing servers)
- Health checks (verifies successful startup)
- Logging (captures output to logs/ directory)
- Status reporting (shows URLs and PIDs)
```

### Development Workflow
1. **Make backend changes** → `./scripts/restart-backend.sh`
2. **Test changes** → Access http://localhost:8000/docs
3. **Frontend still works** → HMR preserves frontend state
4. **Make frontend changes** → HMR handles automatically
5. **Install dependencies** → Use appropriate restart script

## Key Implementation Areas

### YouTube Integration (`src/services/youtube.py`)
```python
# Primary: youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi

# Fallback: yt-dlp for metadata
import yt_dlp

# Extract video ID from various URL formats
# Handle multiple subtitle languages
# Implement retry logic for failures
```

### AI Summarization (`src/services/summarizer.py`)
```python
# Multi-model support
class SummarizerService:
    def __init__(self):
        self.models = {
            'openai': OpenAISummarizer(),
            'anthropic': AnthropicSummarizer(),
            'deepseek': DeepSeekSummarizer()
        }
    
    async def summarize(self, transcript, model='auto'):
        # Implement model selection logic
        # Handle token limits
        # Generate structured summaries
```

### Caching Strategy (`src/services/cache.py`)
```python
# Cache at multiple levels:
# 1. Transcript cache (by video_id)
# 2. Summary cache (by video_id + model + params)
# 3. Export cache (by summary_id + format)

# Use hash for cache keys
import hashlib

def get_cache_key(video_id: str, model: str, params: dict) -> str:
    key_data = f"{video_id}:{model}:{json.dumps(params, sort_keys=True)}"
    return hashlib.sha256(key_data.encode()).hexdigest()
```

## API Endpoint Patterns

### FastAPI Best Practices
```python
from fastapi import APIRouter, HTTPException, BackgroundTasks
from pydantic import BaseModel, HttpUrl

router = APIRouter(prefix="/api", tags=["summarization"])

class SummarizeRequest(BaseModel):
    url: HttpUrl
    model: str = "auto"
    options: dict = {}

@router.post("/summarize")
async def summarize_video(
    request: SummarizeRequest,
    background_tasks: BackgroundTasks
):
    # Validate URL
    # Extract video ID
    # Check cache
    # Queue for processing if needed
    # Return job ID for status checking
```

## Database Schema

```sql
-- Main summaries table
CREATE TABLE summaries (
    id UUID PRIMARY KEY,
    video_id VARCHAR(20) NOT NULL,
    video_title TEXT,
    video_url TEXT NOT NULL,
    transcript TEXT,
    summary TEXT,
    key_points JSONB,
    chapters JSONB,
    model_used VARCHAR(50),
    processing_time FLOAT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Cache for performance
CREATE INDEX idx_video_id ON summaries(video_id);
CREATE INDEX idx_created_at ON summaries(created_at);
```

## Error Handling

```python
class YouTubeError(Exception):
    """Base exception for YouTube-related errors"""
    pass

class TranscriptNotAvailable(YouTubeError):
    """Raised when transcript cannot be extracted"""
    pass

class AIServiceError(Exception):
    """Base exception for AI service errors"""
    pass

class TokenLimitExceeded(AIServiceError):
    """Raised when content exceeds model token limit"""
    pass

# Global error handler
@app.exception_handler(YouTubeError)
async def youtube_error_handler(request, exc):
    return JSONResponse(
        status_code=400,
        content={"error": str(exc), "type": "youtube_error"}
    )
```

## Environment Variables

```bash
# Required
OPENAI_API_KEY=sk-...        # At least one AI key required
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...
DATABASE_URL=sqlite:///./data/youtube_summarizer.db
SECRET_KEY=your-secret-key

# Optional but recommended
YOUTUBE_API_KEY=AIza...       # For metadata and quota
REDIS_URL=redis://localhost:6379/0
RATE_LIMIT_PER_MINUTE=30
MAX_VIDEO_LENGTH_MINUTES=180
```

## Testing Guidelines

### Test Runner Integration

The project uses a comprehensive test runner system for efficient testing:

```bash
# Run specific test modules during development
./run_tests.sh run-specific "backend/tests/unit/test_youtube_service.py"

# Fast feedback loop (discovered 229 tests)
./run_tests.sh run-unit --fail-fast

# Comprehensive testing with coverage
./run_tests.sh run-all --coverage --reports html,json
```

### Unit Test Structure
```python
# tests/unit/test_youtube_service.py
import pytest
from unittest.mock import Mock, patch
from src.services.youtube import YouTubeService

@pytest.fixture
def youtube_service():
    return YouTubeService()

@pytest.mark.unit  # Test runner marker for categorization
def test_extract_video_id(youtube_service):
    """Test video ID extraction from various URL formats."""
    urls = [
        ("https://youtube.com/watch?v=abc123", "abc123"),
        ("https://youtu.be/xyz789", "xyz789"),
        ("https://www.youtube.com/embed/qwe456", "qwe456")
    ]
    for url, expected_id in urls:
        assert youtube_service.extract_video_id(url) == expected_id
```

### Integration Test Pattern
```python
# tests/integration/test_api.py
import pytest
from fastapi.testclient import TestClient
from src.main import app

client = TestClient(app)

@pytest.mark.integration  # Test runner marker for categorization
@pytest.mark.api
def test_summarize_endpoint():
    """Test video summarization API endpoint."""
    response = client.post("/api/summarize", json={
        "url": "https://youtube.com/watch?v=test123",
        "model": "openai"
    })
    assert response.status_code == 200
    assert "job_id" in response.json()
```

### Test Runner Categories

The test runner automatically categorizes tests using markers and file patterns:

```python
# Test markers for intelligent categorization
@pytest.mark.unit           # Fast, isolated unit tests
@pytest.mark.integration    # Database/API integration tests  
@pytest.mark.auth          # Authentication and security tests
@pytest.mark.api           # API endpoint tests
@pytest.mark.pipeline      # End-to-end pipeline tests
@pytest.mark.slow          # Tests taking >5 seconds

# Run specific categories
# ./run_tests.sh run-integration  # Runs integration + api marked tests
# ./run_tests.sh list --category unit  # Shows all unit tests
```

## Performance Optimization

1. **Async Everything**: Use async/await for all I/O operations
2. **Background Tasks**: Process summaries in background
3. **Caching Layers**: 
   - Memory cache for hot data
   - Database cache for persistence
   - CDN for static exports
4. **Rate Limiting**: Implement per-IP and per-user limits
5. **Token Optimization**: 
   - Chunk long transcripts
   - Use map-reduce for summaries
   - Implement progressive summarization

## Security Considerations

1. **Input Validation**: Validate all YouTube URLs
2. **API Key Management**: Use environment variables, never commit keys
3. **Rate Limiting**: Prevent abuse and API exhaustion
4. **CORS Configuration**: Restrict to known domains in production
5. **SQL Injection Prevention**: Use parameterized queries
6. **XSS Protection**: Sanitize all user inputs
7. **Authentication**: Implement JWT for user sessions (Phase 3)

## Common Issues and Solutions

### Issue: Transcript Not Available
```python
# Solution: Implement fallback chain
try:
    transcript = await get_youtube_transcript(video_id)
except TranscriptNotAvailable:
    # Try auto-generated captions
    transcript = await get_auto_captions(video_id)
    if not transcript:
        # Use audio transcription as last resort
        transcript = await transcribe_audio(video_id)
```

### Issue: Token Limit Exceeded
```python
# Solution: Implement chunking
def chunk_transcript(transcript, max_tokens=3000):
    chunks = []
    current_chunk = []
    current_tokens = 0
    
    for segment in transcript:
        segment_tokens = count_tokens(segment)
        if current_tokens + segment_tokens > max_tokens:
            chunks.append(current_chunk)
            current_chunk = [segment]
            current_tokens = segment_tokens
        else:
            current_chunk.append(segment)
            current_tokens += segment_tokens
    
    if current_chunk:
        chunks.append(current_chunk)
    
    return chunks
```

### Issue: Rate Limiting
```python
# Solution: Implement exponential backoff
import asyncio
from typing import Optional

async def retry_with_backoff(
    func, 
    max_retries: int = 3,
    initial_delay: float = 1.0
) -> Optional[Any]:
    delay = initial_delay
    for attempt in range(max_retries):
        try:
            return await func()
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            await asyncio.sleep(delay)
            delay *= 2  # Exponential backoff
```

## Development Tips

1. **Start with Task 1**: Setup and environment configuration
2. **Test Early**: Write tests as you implement features
3. **Use Type Hints**: Improve code quality and IDE support
4. **Document APIs**: Use FastAPI's automatic documentation
5. **Log Everything**: Implement comprehensive logging for debugging
6. **Cache Aggressively**: Reduce API calls and improve response times
7. **Handle Errors Gracefully**: Provide helpful error messages to users

## Task Master Integration

This project uses Task Master for task management. Key commands:

```bash
# View current progress
task-master list

# Get detailed task info
task-master show 1

# Expand task into subtasks
task-master expand --id=1 --research

# Update task with progress
task-master update-task --id=1 --prompt="Completed API structure"

# Complete task
task-master set-status --id=1 --status=done
```

## BMad Method Documentation Structure

### Core Documentation
- **[Project README](README.md)** - General project information and setup
- **[Architecture](docs/architecture.md)** - Complete technical architecture specification  
- **[Front-End Spec](docs/front-end-spec.md)** - UI/UX requirements and component specifications
- **[Original PRD](docs/prd.md)** - Complete product requirements document

### Epic and Story Management
- **[Epic Index](docs/prd/index.md)** - Epic overview and progress tracking
- **[Epic 1](docs/prd/epic-1-foundation-core-youtube-integration.md)** - Foundation epic details
- **[Epic 2](docs/prd/epic-2-ai-summarization-engine.md)** - AI engine epic details  
- **[Epic 3](docs/prd/epic-3-enhanced-user-experience.md)** - Advanced features epic
- **[Stories](docs/stories/)** - Individual story implementations

### Current Story Files

**Epic 1 - Foundation (Sprint 1)**:
- **[Story 1.1](docs/stories/1.1.project-setup-infrastructure.md)** - ✅ Project setup (COMPLETED)
- **[Story 1.2](docs/stories/1.2.youtube-url-validation-parsing.md)** - ✅ URL validation (COMPLETED)
- **[Story 1.3](docs/stories/1.3.transcript-extraction-service.md)** - ✅ Transcript extraction (COMPLETED)
- **[Story 1.4](docs/stories/1.4.basic-web-interface.md)** - ✅ Web interface (COMPLETED)
- **[Story 1.5](docs/stories/1.5.video-download-storage-service.md)** - 📋 Video download service (READY)

**Epic 2 - AI Engine (Sprints 2-3)**:
- **[Story 2.1](docs/stories/2.1.single-ai-model-integration.md)** - 📋 OpenAI integration (READY)
- **[Story 2.2](docs/stories/2.2.summary-generation-pipeline.md)** - 📋 Pipeline orchestration (READY)
- **[Story 2.3](docs/stories/2.3.caching-system-implementation.md)** - 📋 Caching system (READY)
- **[Story 2.4](docs/stories/2.4.multi-model-support.md)** - 📋 Multi-model AI (READY)
- **[Story 2.5](docs/stories/2.5.export-functionality.md)** - 📋 Export features (READY)

### Development Workflow
1. **Check Epic Progress**: Review [Epic Index](docs/prd/index.md) for current status
2. **Review Next Story**: Read story file for implementation details  
3. **Follow Dev Notes**: Use architecture references and technical specifications
4. **Implement & Test**: Follow story tasks/subtasks systematically
5. **Update Progress**: Mark story complete and update epic status

### Story-Based Implementation Priority

**Current Focus**: Epic 1 - Foundation & Core YouTube Integration

**Sprint 1 (Weeks 1-2)** - Epic 1 Implementation:
1. ✅ **Story 1.2** - YouTube URL Validation and Parsing (COMPLETED)
2. ✅ **Story 1.3** - Transcript Extraction Service (COMPLETED with mocks)
3. ✅ **Story 1.4** - Basic Web Interface (COMPLETED)
4. **Story 1.5** - Video Download and Storage Service (12-16 hours) ⬅️ **START HERE**

**Sprint 2 (Weeks 3-4)** - Epic 2 Core:
4. **Story 2.1** - Single AI Model Integration (12-16 hours)
5. **Story 2.2** - Summary Generation Pipeline (16-20 hours)
6. **Story 2.3** - Caching System Implementation (12-16 hours)

**Sprint 3 (Weeks 5-6)** - Epic 2 Advanced:
7. **Story 2.4** - Multi-Model Support (16-20 hours)
8. **Story 2.5** - Export Functionality (12-16 hours)

**Developer Resources**:
- [Developer Handoff Guide](docs/DEVELOPER_HANDOFF.md) - Start here for implementation
- [Sprint Planning](docs/SPRINT_PLANNING.md) - Detailed sprint breakdown
- [Story Files](docs/stories/) - All stories with complete Dev Notes

## Enhanced Export System (Story 4.4) 🚀

### Professional Document Generation with AI Intelligence
The Enhanced Export System provides business-grade document generation with domain-specific AI optimization and professional formatting.

**Key Features**:
- **Executive Summary Generation** - Business-focused summaries with ROI analysis
- **Timestamped Navigation** - Clickable `[HH:MM:SS]` YouTube links for sections
- **6 Domain-Specific Templates** - Educational, Business, Technical, Content Creation, Research, General
- **AI-Powered Recommendations** - Intelligent domain matching based on content analysis
- **Professional Formatting** - Executive-ready markdown with table of contents

**Implementation Components**:
- **File**: `backend/services/executive_summary_generator.py` - Business-focused AI summaries
- **File**: `backend/services/timestamp_processor.py` - Semantic section detection  
- **File**: `backend/services/enhanced_markdown_formatter.py` - Professional document templates
- **File**: `backend/services/enhanced_template_manager.py` - Domain presets and custom templates
- **API**: `backend/api/enhanced_export.py` - Complete REST endpoints

**Usage**:
```bash
# Test enhanced export system structure
python test_enhanced_export_structure.py

# API Endpoints
POST /api/export/enhanced          # Generate enhanced export
GET /api/export/templates          # List domain templates
POST /api/export/recommendations   # Get domain suggestions
```

**Professional Output Example**:
```markdown
# Video Analysis: Executive Briefing

## Executive Summary
- Strategic business value with $2.5M potential savings
- Implementation roadmap with 6-month timeline
- Key action items for leadership decision-making

## Table of Contents
- **[00:01:30](https://youtube.com/watch?v=...&t=90s)** Strategy Overview
- **[00:05:45](https://youtube.com/watch?v=...&t=345s)** ROI Analysis
```

**Domain Intelligence**:
- **Educational**: Learning objectives, pedagogy, study notes format
- **Business**: ROI analysis, strategic implications, executive briefings  
- **Technical**: Implementation details, architecture, best practices
- **Content Creation**: Engagement strategies, audience insights
- **Research**: Academic rigor, methodology, evidence analysis
- **General**: Balanced analysis for any content type

## Admin Page Implementation 🛠️

### No-Authentication Admin Interface
A standalone admin page provides immediate access to YouTube Summarizer functionality without authentication barriers.

**Key Implementation Details**:
- **File**: `frontend/src/pages/AdminPage.tsx`
- **Route**: `/admin` (bypasses ProtectedRoute wrapper in App.tsx)
- **URL**: `http://localhost:3002/admin`
- **Backend**: CORS configured to accept requests from port 3002

**Visual Design**:
- Orange "Admin Mode" theme with Shield icon  
- Status badges: "Direct Access • Full Functionality • Testing Mode"
- Footer: "Admin Mode - For testing and development purposes"

**Usage**:
1. Start services: `python backend/main.py` + `npm run dev`
2. Visit: `http://localhost:3002/admin` 
3. Test with: `https://www.youtube.com/watch?v=DCquejfz04A`

**Technical Notes**:
- Uses same components as protected dashboard (SummarizeForm, ProgressTracker, TranscriptViewer)
- No AuthContext dependencies - completely self-contained
- Perfect for testing, demos, and development workflow

---

*This guide is specifically tailored for Claude Code development on the YouTube Summarizer project.*