trendyol-analiz/docs/ARCHITECTURE.md

Sistem Mimarisi

Trendyol Product Dashboard teknik mimari dokümantasyonu.

Genel Bakış

Trendyol Product Dashboard, Trendyol e-ticaret platformundan ürün verilerini çekip analiz eden full-stack bir uygulamadır.

Temel Özellikler:

• Kategori bazlı ürün verisi çekme (scraping)
• Otomatik rapor oluşturma ve arka plan işleme
• 7 tab'lı çok boyutlu analitik dashboard
• Gerçek zamanlı ilerleme takibi
• Sosyal kanıt metrikleri ve yorum analizi

3 Katmanlı Mimari

┌─────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                   │
│              (React Frontend - Admin Panel)             │
│  • CategoryManagement • ReportGeneration               │
│  • ReportList • ReportDashboard (7 tab)                │
└─────────────────────────────────────────────────────────┘
                        ↕ HTTP/REST API
┌─────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER                    │
│              (FastAPI Backend - main.py)                │
│  • REST API Endpoints • Business Logic                  │
│  • Data Processing • External API Integration          │
└─────────────────────────────────────────────────────────┘
                        ↕ ORM (SQLAlchemy)
┌─────────────────────────────────────────────────────────┐
│                      DATA LAYER                         │
│              (SQLite Database + JSON Files)             │
│  • trendyol.db (SQLite) • categories/*.json            │
│  • reports/*.json                                      │
└─────────────────────────────────────────────────────────┘

Teknoloji Stack

Backend

Teknoloji	Versiyon	Amaç
Python	3.8+	Runtime
FastAPI	0.104.1	Web framework
SQLAlchemy	2.0.45	ORM
Uvicorn	0.24.0	ASGI server
Requests	2.31.0	HTTP client

Frontend

Teknoloji	Versiyon	Amaç
React	19.2.0	UI library
Vite	7.2.2	Build tool
Recharts	3.4.1	Grafikler
Tailwind CSS	4.1.17	Styling
React Router DOM	7.9.5	Routing
Axios	1.13.2	HTTP client

Veri Depolama

• SQLite: İlişkisel veritabanı (kategoriler, raporlar, snapshots)
• JSON Files: Ürün verileri ve raporlar (categories/, reports/)

Dashboard Tab Yapısı (7 Tab)

Tab ID	Tab Adı	Açıklama
overview	Genel Bakış	KPI kartları, özet grafikler
brand	Marka	Marka analizi, pazar payı
category	Kategori	Kategori dağılımı
origin	Menşei	Ülke bazlı analiz
barcode	Barkod	Barkod veri analizi
keyword	Keyword Aracı	Anahtar kelime analizi
product-finder	Ürün Bulma	Ürün arama/filtreleme

Veritabanı Şeması

Category Model

id: Integer (Primary Key)
name: String
parent_id: Integer (Foreign Key → categories.id)
trendyol_category_id: Integer
trendyol_url: String
is_active: Boolean
created_at: DateTime

Snapshot Model

id: Integer (Primary Key)
category_id: Integer (Foreign Key → categories.id)
snapshot_month: String (örn: "2024-11")
total_products: Integer
avg_price: Integer
json_file_path: String
scraped_at: DateTime

Report Model

id: Integer (Primary Key)
name: String
category_id: Integer (Foreign Key → categories.id)
total_products: Integer
total_subcategories: Integer
json_file_path: String
created_at: DateTime

EnrichmentError Model

id: Integer (Primary Key)
report_id: Integer
product_id: Integer
endpoint: String (reviews | social | questions)
error_type: String (timeout | dns | http | other)
message: String
status_code: Integer
created_at: DateTime

İlişki Diyagramı

Category (1) ──< (N) Snapshot
Category (1) ──< (N) Report
Category (1) ──< (N) Category (self-referential)

Veri Akışı

Rapor Oluşturma Akışı

1. POST /api/reports/create → task_id döner
2. BackgroundTask başlar
3. Client: GET /api/reports/progress/{task_id} (polling)
4. Backend: Trendyol API tarama (her alt kategori)
5. JSON dosyası kayıt → reports/
6. DB'ye rapor kaydı
7. Progress: 100%

Dashboard Veri Akışı

1. GET /api/dashboard/{report_id}
2. Backend: JSON okur, on-demand işler/toplar
3. Cache kontrolü (BoundedCache)
4. Response: { kpis: {...}, charts: {...}, all_products: [...] }
5. Frontend: Hazır objeleri render eder

API Endpoint Yapısı

Kategori Endpoints

Endpoint	Metod	Açıklama
/categories/main	GET	Ana kategoriler
/categories/{id}	GET	Kategori detayı
/categories/{id}/subcategories	GET	Alt kategoriler

Rapor Endpoints

Endpoint	Metod	Açıklama
/api/reports	GET	Rapor listesi
/api/reports/create	POST	Rapor oluştur
/api/reports/progress/{task_id}	GET	İlerleme durumu
/api/reports/{id}	GET/DELETE	Rapor detay/sil

Dashboard Endpoints

Endpoint	Metod	Açıklama
/api/dashboard/{report_id}	GET	Dashboard verisi
/api/dashboard/{report_id}/keyword-analysis	GET	Keyword analizi
/api/dashboard/{report_id}/product-finder	POST	Ürün arama

Caching Stratejisi

Backend Cache (BoundedCache)

maxsize: 100 item
TTL: 3600 saniye (1 saat)
eviction: LRU (Least Recently Used)
thread-safe: Evet

Frontend Cache

• Browser HTTP cache
• API response caching
• React.memo ile component memoization

Güvenlik Özellikleri

Özellik	Açıklama
CORS	Explicit origin whitelisting
Input Validation	Pydantic models
Path Traversal	Dosya yolu kontrolü
Rate Limiting	2 istek/saniye (sosyal kanıt)
Timeout	Tüm external çağrılarda timeout

Performans Metrikleri

Metrik	Değer
Dashboard yükleme	2-5 saniye
Tab değiştirme	<500ms
API response (cached)	<200ms
API response (uncached)	1-5 saniye
Rapor oluşturma	5-30 dakika

Performans Optimizasyonları

Backend

• Request deduplication
• Exponential backoff (%75 istek azaltma)
• Circuit breaker pattern
• Connection pooling

Frontend

• Lazy loading (%65 bundle azaltma)
• Code splitting
• Debouncing
• React.memo

Konfigürasyon

API Timeout Değerleri

Tip	Süre
STANDARD	30s
DASHBOARD	180s
ENRICHMENT	120s
KEYWORD_ANALYSIS	300s

Environment Variables

Frontend (.env):

VITE_API_URL=http://127.0.0.1:8001

Proje Yapısı

product_Dashboard/
├── backend/
│   ├── main.py           # Ana API (~4400 satır)
│   ├── database.py       # SQLAlchemy modelleri
│   ├── scraper.py        # Trendyol scraping
│   └── requirements.txt
│
├── admin-panel/
│   └── src/
│       ├── components/
│       │   ├── ReportDashboard.jsx  # 7-tab dashboard
│       │   └── dashboard-tabs/      # Tab componentleri
│       ├── config/api.js
│       └── constants/tabGroups.js
│
├── categories/           # 1842 JSON dosyası
├── reports/              # Oluşturulan raporlar
└── docs/                 # Dokümantasyon

Gelecek Geliştirmeler

• PostgreSQL migration
• WebSocket desteği (real-time updates)
• CI/CD pipeline
• Docker containerization
• Application monitoring

---

Versiyon: 2.1.0 | Son Güncelleme: Ocak 2025