indir-fe/plans/social-media-downloader-plan.md

# Sosyal Medya İndirici - Mimari Plan

> **Tarih:** 2026-03-05
> **Öncelik:** Yüksek
> **Karmaşıklık:** Düşük-Orta
> **Yaklaşım:** Basit ve Minimal

---

## 📋 Özet

Sosyal medya platformlarından (Instagram, YouTube, TikTok, X, Facebook vb.) video/post indirme özelliği. Kullanıcı bir URL girer, sistem içeriği tespit eder ve indirir.

### Basitleştirilmiş Gereksinimler

- ❌ Auth/giriş sistemi **YOK** (herkes kullanabilir)
- ✅ Basit IP-based rate limiting (abuse önleme)
- ✅ Public Cobalt API kullanımı
- ✅ Minimal ve temiz UI

---

## 🎯 Gereksinimler

### Fonksiyonel Gereksinimler

- URL input ile çoklu platform desteği
- Tek tıkla indirme
- Video kalite seçimi (mümkünse)
- İndirme ilerleme durumu
- Hata yönetimi ve kullanıcı bildirimleri

### Fonksiyonel Olmayan Gereksinimler

- **Güvenlik:** Rate limiting, input validation, abuse prevention
- **Performans:** Async processing, streaming downloads
- **UX:** Responsive design, dark/light mode, i18n support
- **Reliability:** Error recovery, timeout handling

---

## 🏗️ Mimari Tasarım

### High-Level Architecture

```mermaid
flowchart TB
    subgraph Frontend[Frontend - Next.js]
        UI[Download Page]
        Form[URL Input Form]
        Progress[Progress Indicator]
        Result[Download Result]
    end

    subgraph API[Next.js API Routes]
        Validate[Input Validation]
        Detect[Platform Detection]
        RateLimit[Rate Limiter]
        Download[Download Handler]
    end

    subgraph External[External Services]
        Cobalt[Cobalt API]
        YtDlp[yt-dlp wrapper]
        Direct[Direct URL Fetch]
    end

    UI --> Form
    Form --> Validate
    Validate --> RateLimit
    RateLimit --> Detect
    Detect --> Download
    Download --> Cobalt
    Download --> YtDlp
    Download --> Direct
    Cobalt --> Result
    YtDlp --> Result
    Direct --> Result
```

---

## 🔐 Güvenlik Katmanları

### 1. Input Validation & Sanitization

```typescript
// src/lib/utils/url-validator.ts
const ALLOWED_DOMAINS = [
  "youtube.com",
  "youtu.be",
  "instagram.com",
  "instagr.am",
  "tiktok.com",
  "vm.tiktok.com",
  "twitter.com",
  "x.com",
  "facebook.com",
  "fb.watch",
  "vimeo.com",
  "pinterest.com",
];

export function validateUrl(url: string): ValidationResult {
  // 1. URL format check
  // 2. Protocol check (https only)
  // 3. Domain whitelist check
  // 4. XSS prevention
  // 5. SQL injection prevention
}
```

### 2. Rate Limiting

```typescript
// src/lib/security/rate-limiter.ts
const RATE_LIMIT_CONFIG = {
  anonymous: { requests: 5, window: 3600 }, // 5 requests/hour
  authenticated: { requests: 20, window: 3600 }, // 20 requests/hour
  premium: { requests: 100, window: 3600 }, // 100 requests/hour
};
```

**Stratejiler:**

- IP-based limiting (Redis/Memory store)
- User-based limiting (auth token)
- Global rate limit (DDoS prevention)

### 3. Abuse Prevention

- **URL Pattern Blocking:** Malicious patterns engelleme
- **Bot Detection:** User-agent analysis
- **Request Fingerprinting:** Browser fingerprinting
- **CAPTCHA:** Şüpheli aktivitede CAPTCHA tetikleme

### 4. Content Security

- **Virus Scanning:** İndirilen dosyaları tara
- **File Size Limits:** Maksimum dosya boyutu
- **Content-Type Validation:** Sadece izin verilen formatlar

---

## 📁 Dosya Yapısı

```
src/
├── app/
│   ├── [locale]/
│   │   └── (site)/
│   │       └── download/
│   │           └── page.tsx              # Download page
│   └── api/
│       └── download/
│           ├── route.ts                   # Main download endpoint
│           └── info/
│               └── route.ts               # Get video info endpoint
├── components/
│   └── site/
│       └── download/
│           ├── download-form.tsx          # URL input form
│           ├── download-result.tsx        # Result display
│           ├── platform-badge.tsx         # Platform indicator
│           ├── quality-selector.tsx       # Quality options
│           └── download-progress.tsx      # Progress indicator
├── lib/
│   ├── api/
│   │   └── download/
│   │       ├── types.ts                   # TypeScript interfaces
│   │       ├── service.ts                 # API service functions
│   │       └── use-hooks.ts               # React Query hooks
│   ├── download/
│   │   ├── platform-detector.ts           # URL -> Platform mapping
│   │   ├── cobalt-client.ts               # Cobalt API client
│   │   └── download-manager.ts            # Download orchestration
│   └── security/
│       ├── rate-limiter.ts                # Rate limiting logic
│       ├── url-validator.ts               # URL validation
│       └── abuse-detector.ts              # Abuse detection
└── types/
    └── download.ts                        # Shared types
```

---

## 🔌 API Endpoints

### POST /api/download

**Request:**

```typescript
interface DownloadRequest {
  url: string; // Sosyal medya URL
  quality?: "high" | "medium" | "low";
  format?: "mp4" | "mp3" | "webm";
}
```

**Response:**

```typescript
interface DownloadResponse {
  success: boolean;
  data?: {
    downloadUrl: string;
    filename: string;
    fileSize: number;
    platform: Platform;
    metadata: VideoMetadata;
  };
  error?: {
    code: ErrorCode;
    message: string;
  };
}
```

### POST /api/download/info

**Request:**

```typescript
interface InfoRequest {
  url: string;
}
```

**Response:**

```typescript
interface InfoResponse {
  success: boolean;
  data?: {
    platform: Platform;
    title: string;
    thumbnail: string;
    duration: number;
    qualities: QualityOption[];
  };
}
```

---

## 🌐 Platform Detection Algorithm

```typescript
// src/lib/download/platform-detector.ts

interface PlatformConfig {
  name: Platform;
  domains: string[];
  patterns: RegExp[];
  extractor: ExtractorType;
}

const PLATFORM_CONFIGS: PlatformConfig[] = [
  {
    name: "youtube",
    domains: ["youtube.com", "youtu.be", "music.youtube.com"],
    patterns: [
      /youtube\.com\/watch\?v=[\w-]+/,
      /youtu\.be\/[\w-]+/,
      /youtube\.com\/shorts\/[\w-]+/,
    ],
    extractor: "cobalt",
  },
  {
    name: "instagram",
    domains: ["instagram.com", "instagr.am"],
    patterns: [/instagram\.com\/(p|reel|tv)\/[\w-]+/],
    extractor: "cobalt",
  },
  {
    name: "tiktok",
    domains: ["tiktok.com", "vm.tiktok.com"],
    patterns: [/tiktok\.com\/@[\w.]+\/video\/\d+/, /vm\.tiktok\.com\/[\w-]+/],
    extractor: "cobalt",
  },
  {
    name: "twitter",
    domains: ["twitter.com", "x.com"],
    patterns: [/twitter\.com\/\w+\/status\/\d+/, /x\.com\/\w+\/status\/\d+/],
    extractor: "cobalt",
  },
  {
    name: "facebook",
    domains: ["facebook.com", "fb.watch"],
    patterns: [/facebook\.com\/.*\/videos\/\d+/, /fb\.watch\/[\w-]+/],
    extractor: "cobalt",
  },
];

export function detectPlatform(url: string): Platform | null {
  const urlObj = new URL(url);

  for (const config of PLATFORM_CONFIGS) {
    if (config.domains.some((d) => urlObj.hostname.includes(d))) {
      return config.name;
    }
  }

  return null;
}
```

---

## 🎨 UI Component Hierarchy

```mermaid
flowchart TD
    Page[DownloadPage] --> Form[DownloadForm]
    Page --> Result[DownloadResult]

    Form --> Input[URLInput]
    Form --> PlatformBadge[PlatformBadge]
    Form --> QualitySelector[QualitySelector]
    Form --> SubmitButton[SubmitButton]

    Result --> Progress[DownloadProgress]
    Result --> SuccessResult[SuccessResult]
    Result --> ErrorResult[ErrorResult]

    Progress --> ProgressBar[ProgressBar]
    Progress --> StatusText[StatusText]

    SuccessResult --> FilePreview[FilePreview]
    SuccessResult --> DownloadButton[DownloadButton]

    ErrorResult --> ErrorIcon[ErrorIcon]
    ErrorResult --> ErrorMessage[ErrorMessage]
    ErrorResult --> RetryButton[RetryButton]
```

---

## 🔄 Veri Akışı

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant API as Next.js API
    participant Validator
    participant RateLimiter
    participant Cobalt as Cobalt API

    User->>Frontend: URL Gir + İndir
    Frontend->>Frontend: URL Format Validation
    Frontend->>API: POST /api/download/info
    API->>Validator: Validate URL
    Validator-->>API: Valid
    API->>RateLimiter: Check Rate Limit
    RateLimiter-->>API: Allowed
    API->>Cobalt: Get Video Info
    Cobalt-->>API: Video Metadata
    API-->>Frontend: Info Response
    Frontend->>User: Show Options

    User->>Frontend: Select Quality
    Frontend->>API: POST /api/download
    API->>Cobalt: Request Download
    Cobalt-->>API: Download URL
    API-->>Frontend: Download Response
    Frontend->>User: Download File
```

---

## 🛡️ Güvenlik Checklist

### Input Security

- [ ] URL format validation
- [ ] Protocol whitelist (https only)
- [ ] Domain whitelist
- [ ] XSS prevention (DOMPurify)
- [ ] SQL injection prevention
- [ ] Path traversal prevention

### Rate Limiting

- [ ] IP-based limiting
- [ ] User-based limiting (authenticated)
- [ ] Global request limiting
- [ ] Sliding window algorithm

### Content Security

- [ ] File type validation
- [ ] File size limits
- [ ] Virus/malware scanning (optional)
- [ ] Content-Disposition headers

### API Security

- [ ] CSRF protection
- [ ] Content-Type validation
- [ ] Request size limits
- [ ] Timeout handling

---

## 📊 Error Handling Strategy

| Error Code             | Message                    | User Action                  |
| ---------------------- | -------------------------- | ---------------------------- |
| `INVALID_URL`          | Geçersiz URL formatı       | URL'yi kontrol et            |
| `UNSUPPORTED_PLATFORM` | Bu platform desteklenmiyor | Desteklenen platformları gör |
| `RATE_LIMIT_EXCEEDED`  | Çok fazla istek            | Bekle veya giriş yap         |
| `VIDEO_NOT_FOUND`      | Video bulunamadı           | URL'yi kontrol et            |
| `VIDEO_PRIVATE`        | Video özel/gizli           | Herkese açık video kullan    |
| `DOWNLOAD_FAILED`      | İndirme başarısız          | Tekrar dene                  |
| `FILE_TOO_LARGE`       | Dosya çok büyük            | Düşük kalite seç             |

---

## 🧪 Test Strategy

### Unit Tests

- URL validator fonksiyonları
- Platform detector logic
- Rate limiter calculations
- API service functions

### Integration Tests

- API endpoint tests
- External API mock tests
- Error scenario tests

### E2E Tests

- Complete download flow
- Error handling UI
- Rate limit scenarios

---

## 📦 Dependencies

### Production

```json
{
  "axios": "^1.x",
  "zod": "^3.x"
}
```

### Development

```json
{
  "@types/node": "^20",
  "vitest": "^1.x",
  "msw": "^2.x"
}
```

---

## 🚀 Implementation Phases

### Phase 1: Core Infrastructure

1. URL validation ve platform detection
2. API route structure
3. Basic UI components

### Phase 2: External API Integration

1. Cobalt API client
2. Download orchestration
3. Error handling

### Phase 3: Security Layer

1. Rate limiting implementation
2. Abuse detection
3. Input sanitization

### Phase 4: UI/UX Polish

1. Progress indicators
2. Responsive design
3. Dark/light mode
4. i18n translations

### Phase 5: Testing & Optimization

1. Unit tests
2. Integration tests
3. Performance optimization

---

## 💡 Önemli Notlar

1. **Cobalt API:** Açık kaynaklı, self-hosted bir sosyal medya indirici API. Kullanımı için:
   - Self-hosted instance (önerilen)
   - Public instance (rate limit riski)

2. **Copyright Uyarısı:** Kullanıcılara telif hakkı uyarısı gösterilmeli

3. **Terms of Service:** Her platformun ToS'u kontrol edilmeli

4. **Monitoring:** API kullanımı ve hata oranları izlenmeli

---

## ❓ Açık Sorular

1. Cobalt API self-hosted mu kullanılacak yoksa public instance mi?
2. Video maksimum boyutu ne olacak?
3. Oturum açmamış kullanıcılar için limit ne kadar?
4. İndirilen dosyalar sunucuda saklanacak mı (cache)?