youtube-cli/web/PLAN.md

youtube-cli/ ├── youtube_cli/ # Core CLI application (existing) ├── youtube_tui/ # Textual TUI (existing) ├── web/ # React web interface (NEW) - COMPLETE ✓ │ ├── server/ # Backend API server (Flask) - COMPLETE │ │ ├── app.py # Flask application with 15 endpoints │ │ ├── models/ │ │ └── routes/ │ ├── web-app/ # React frontend - COMPLETE │ │ ├── public/ │ │ └── src/ │ │ ├── api/ # API client functions │ │ ├── components/# UI components │ │ └── pages/ # Page components │ ├── tests/ # E2E tests (Playwright) │ ├── package.json │ ├── requirements-web.txt │ └── PLAN.md └── ...

## Project Status: COMPLETE ✓

### What's Built

A full-stack web application with:
- **Backend**: Flask API server exposing YouTubeCLI functionality
- **Frontend**: React + TypeScript application
- **Tests**: Playwright E2E tests

---

## Implementation Phases

### Phase 1: Backend API Server (Flask) - COMPLETE ✓

**Goal**: Create a REST API that exposes YouTubeCLI functionality

**Files created**:
- `web/server/app.py` - Main Flask application with 15 endpoints
- `web/server/models/__init__.py` - Data models package
- `web/server/routes/__init__.py` - Routes package
- `web/requirements-web.txt` - Python dependencies

**API Endpoints**:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/config` | GET | Get configuration |
| `/api/categories` | GET | Get download categories |
| `/api/search?q=query&page=1` | GET | Search for videos |
| `/api/download` | POST | Download a video |
| `/api/download/playlist` | POST | Download a playlist |
| `/api/archive` | GET | Get download archive |
| `/api/archive/<video_id>` | DELETE | Remove from archive |
| `/api/queue` | GET | Get all queue items |
| `/api/queue/<id>` | DELETE | Remove from queue |
| `/api/queue/<id>/retry` | POST | Retry download |
| `/api/queue/<id>/cancel` | POST | Cancel download |
| `/api/queue/<id>/status` | GET | Get download status |
| `/api/queue/clear/completed` | POST | Clear completed items |
| `/api/queue/clear/failed` | POST | Clear failed items |

---

### Phase 2: React Application Setup - COMPLETE ✓

**Goal**: Create a modern React app with TypeScript

**Files created**:
- `web/web-app/package.json` - Dependencies (React, Vite, Tailwind, Playwright)
- `web/web-app/vite.config.ts` - Vite with API proxy to Flask backend
- `web/web-app/tsconfig.json` - TypeScript configuration
- `web/web-app/tailwind.config.js` - Tailwind CSS configuration
- `web/web-app/index.html` - HTML entry point
- `web/web-app/src/main.tsx` - React entry point
- `web/web-app/src/App.tsx` - Main app with routing
- `web/web-app/src/index.css` - Global CSS with Tailwind imports

---

### Phase 3: Core Features - COMPLETE ✓

#### API Layer (`src/api/`)
- `client.ts` - Axios instance pointing to `http://localhost:4096`
- `search.ts` - Search API functions
- `download.ts` - Download API functions
- `queue.ts` - Queue management API functions
- `archive.ts` - Archive API functions

#### Components (`src/components/`)
- `Navbar.tsx` - Navigation bar with links to Search, Queue, Archive

#### Pages (`src/pages/`)

**SearchPage.tsx** (`/`)
- Search input with YouTube URL or query support
- Recent searches history
- Search button and Enter key support

**SearchResults.tsx** (`/results`)
- Video grid display with thumbnails
- Category selection modal
- Download with progress tracking

**Queue.tsx** (`/queue`)
- Queue table with status tracking (pending/downloading/completed/cancelled/failed)
- Progress bars with polling updates (every 2 seconds)
- Action buttons: Cancel, Retry, Remove, Clear Completed, Clear Failed
- Queue statistics display

**Archive.tsx** (`/archive`)
- List of downloaded videos
- Search/filter archive
- View/download date and metadata
- Remove from archive functionality

---

### Phase 4: Testing - COMPLETE ✓

**Test Framework**: Playwright
**Tests**: `web/web-app/tests/e2e/app.spec.ts`

**Test Coverage**:
- Visit home page
- Search for a video
- Display search results
- Navigate to queue page
- Navigate to archive page

---

### Phase 5: Documentation - COMPLETE ✓

**Files**:
- `web/README.md` - Setup and usage instructions
- `web/requirements-web.txt` - Python dependencies

---

## Build Status

✓ Build completed successfully ✓ No TypeScript errors ✓ E2E tests created (ready to run) ✓ Production bundle: 227.93 kB (73.65 kB gzipped)

---

## Usage

### Development

```bash
# Terminal 1: Start Flask backend
cd web/server
pip install -r requirements-web.txt
python app.py

# Terminal 2: Start React frontend
cd web/web-app
npm install
npm run dev

The frontend will be available at http://localhost:5173 and proxy API requests to the Flask backend on port 4096.

Production

# Build the React app
cd web/web-app
npm run build

# Serve static files with Flask
cd web/server
python app.py

---

Configuration

The application uses the same configuration as the CLI/TUI:

• Config location: ~/.config/youtube_cli/config.json
• Archive location: ~/.config/youtube_cli/downloaded_videos.json

---

Success Metrics

• All TUI features implemented in web interface
• Downloads work reliably
• Queue management functional
• Responsive on desktop and mobile
• Error messages user-friendly
• Build successful
• Tests cover core functionality (E2E tests in place)