downlink/docs/architecture.md

Architecture Documentation

Overview

Downlink is a Next.js application that provides a web interface for downloading YouTube videos and audio files. The application uses server-side processing with yt-dlp and provides a modern, responsive UI built with shadcn/ui.

System Architecture

┌─────────────┐
│   Browser   │
│   (Client)  │
└──────┬──────┘
       │ HTTP Requests
       ▼
┌─────────────────────────────────┐
│      Next.js App Router         │
│  ┌───────────────────────────┐  │
│  │   UI Components (React)   │  │
│  └───────────────────────────┘  │
│  ┌───────────────────────────┐  │
│  │   API Routes              │  │
│  │   - /api/info             │  │
│  │   - /api/download        │  │
│  └───────────┬───────────────┘  │
└──────────────┼──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│      Business Logic Layer       │
│  ┌───────────────────────────┐  │
│  │   lib/youtube.ts          │  │
│  │   - getVideoInfo()        │  │
│  │   - downloadVideo()       │  │
│  └───────────┬───────────────┘  │
└──────────────┼──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│      External Tools             │
│  ┌───────────────────────────┐  │
│  │   yt-dlp (Python)        │  │
│  │   - Video download        │  │
│  │   - Format conversion     │  │
│  └───────────────────────────┘  │
│  ┌───────────────────────────┐  │
│  │   ffmpeg (via yt-dlp)    │  │
│  │   - Audio transcoding     │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘

Component Structure

Frontend Components

app/page.tsx

Main page component containing:

• URL input field
• Video information display
• Format selection (video/audio)
• Download button
• Error handling and success states

UI Components (components/ui/)

shadcn/ui components:

• button.tsx: Button component
• input.tsx: Input field component
• card.tsx: Card container component
• label.tsx: Form label component
• select.tsx: Dropdown select component

Backend Components

API Routes

app/api/info/route.ts

• Handles POST requests for video information
• Validates YouTube URL
• Calls getVideoInfo() from lib/youtube.ts
• Returns video metadata

app/api/download/route.ts

• Handles POST requests for downloads
• Validates request body (url, format, formatType)
• Calls downloadVideo() from lib/youtube.ts
• Returns download URL and file information

Business Logic

lib/youtube.ts Core functionality:

• getVideoInfo(url): Fetches video metadata using yt-dlp
• downloadVideo(request): Downloads and processes video/audio
• ensureDirectories(): Creates necessary directories
• sanitizeFilename(): Sanitizes filenames for safe storage

lib/types.ts Centralized TypeScript type definitions:

• VideoFormat, AudioFormat: Format type unions
• DownloadRequest, DownloadResponse: API request/response types
• VideoInfo, FormatOption: Video metadata types

lib/utils.ts Utility functions:

• cn(): Tailwind class name merger
• isValidYouTubeUrl(): URL validation
• extractYouTubeId(): Extract video ID from URL

Data Flow

Video Information Flow

1. User enters YouTube URL and clicks "Get Info"
2. Frontend sends POST request to /api/info
3. API route validates URL and calls getVideoInfo()
4. getVideoInfo() executes yt-dlp --dump-json
5. JSON response is parsed and formatted
6. Video info (title, thumbnail, duration) returned to frontend
7. Frontend displays video information

Download Flow

1. User selects format and clicks "Download"
2. Frontend sends POST request to /api/download
3. API route validates request and calls downloadVideo()
4. downloadVideo():
   • Generates unique file ID
   • Constructs yt-dlp command based on format
   • Executes download command
   • Moves file to /public/downloads/
   • Returns download URL
5. Frontend receives download URL
6. User can download file via provided link

File Storage

Directory Structure

Downlink/
├── downloads/              # Temporary storage (gitignored)
│   └── [fileId].[ext]     # Downloaded files before processing
├── public/
│   └── downloads/         # Public downloads (gitignored)
│       └── [fileId].[ext] # Final files served to users

File Naming

• Format: [timestamp]-[randomId].[extension]
• Example: 1234567890-abc123.mp4
• Prevents filename conflicts
• Timestamp enables cleanup of old files

Dependencies

Runtime Dependencies

• next: Next.js framework
• react: React library
• react-dom: React DOM rendering
• lucide-react: Icon library
• @radix-ui/*: UI component primitives
• tailwind-merge: Tailwind class merging
• clsx: Conditional class names

System Dependencies

• yt-dlp: Python-based YouTube downloader
• ffmpeg: Media conversion tool (used by yt-dlp)

Development Dependencies

• typescript: TypeScript compiler
• tailwindcss: CSS framework
• eslint: Code linting

Security Considerations

Current Implementation

• URL validation to ensure YouTube URLs only
• Filename sanitization to prevent directory traversal
• Server-side processing (no client-side download logic)

Recommended Enhancements

• Rate limiting to prevent abuse
• File size limits
• User authentication/authorization
• Download quotas per user/IP
• Automatic file cleanup
• CORS configuration
• Input sanitization for all user inputs

Performance Considerations

Current Limitations

• Synchronous file operations (could block for large files)
• No progress tracking during downloads
• Files stored in memory during copy operations
• No caching of video information

Optimization Opportunities

• Stream large files instead of loading into memory
• Implement download progress tracking
• Cache video metadata
• Use background jobs for long-running downloads
• Implement CDN for file serving
• Add database for download history

Deployment Considerations

Requirements

• Node.js 18+ runtime
• Python 3.6+ (for yt-dlp)
• ffmpeg installed on server
• Sufficient disk space for downloads
• Network access to YouTube

Environment Variables

Currently none required, but consider:

• MAX_FILE_SIZE: Maximum file size limit
• CLEANUP_INTERVAL: File cleanup schedule
• ALLOWED_DOMAINS: Allowed video platforms
• STORAGE_PATH: Custom storage location

Scaling Considerations

• Stateless API design (can scale horizontally)
• File storage should be shared (S3, etc.) for multi-instance deployments
• Consider message queue for download processing
• Implement caching layer for video metadata