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

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

// 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

// 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:

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

Response:

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:

interface InfoRequest {
  url: string;
}

Response:

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

---

🌐 Platform Detection Algorithm

// 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

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ışı

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

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

Development

{
  "@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)?