generated from fahricansecer/boilerplate-fe
main
All checks were successful
UI Deploy - indir.bilgich.com 🎨 / build-and-deploy (push) Successful in 4m8s
All checks were successful
UI Deploy - indir.bilgich.com 🎨 / build-and-deploy (push) Successful in 4m8s
This commit is contained in:
521
plans/social-media-downloader-plan.md
Normal file
521
plans/social-media-downloader-plan.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# 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)?
|
||||
Reference in New Issue
Block a user