Serpilen Collection Perakende Ticaret Platformu Mimarisi
Bu doküman; 40 maddelik mimari vizyonun, veri modellerinin, tekil stok motorunun, sipariş yaşam döngüsünün tam teknik haritasını sunar.
Merkezi Veritabanı İlişkileri (ERD)
Bir ürün sistemde yalnızca 1 kez tanımlanır; e-ticaret vitrini, POS terminali ve çoklu depo aynı veritabanı modellerini paylaşır.
[CATEGORIES] ──1:N──< [PRODUCTS] >──1:N── [PRODUCT_VARIANTS]
│ │
│ │
1:N │ 1:N │
▼ ▼
[INVENTORY] <──N:1── [WAREHOUSES]
│
▼
[INVENTORY_LEDGER] (Immutable Değiştirilemez Defter)
▲
│ (Hareket Referansı)
┌───────┴────────┐
▼ ▼
[ORDERS] [PURCHASE_ORDERS]
│ │
[ORDER_ITEMS] [PO_ITEMS]
40 Maddelik Mimari Blueprint Maddeleri
Projenin Kapsamı
Fiziki mağaza, web vitrini ve WMS'i tek bir merkezi ürün/stok kaydı üzerinde birleştiren kurumsal işletim sistemi.
Fonksiyonel Gereksinimler
SKU/barkod bazlı tekil ürün, renk/boyut varyantları, hareket bazlı stok defteri (Stock Ledger), çoklu depo ve web POS.
Fonksiyonel Olmayan Gereksinimler
MySQL (InnoDB) transaction bütünlüğü, < 200ms TTFB yanıt süresi, OWASP Top 10 ve PCI-DSS ilkeleri.
Kullanıcı Rolleri & RBAC
SUPER_ADMIN, STORE_MANAGER, WAREHOUSE_KEEPER, CASHIER, B2C_CUSTOMER granular yetkilendirmesi.
Context Diagramı
Platform; B2C vitrin, Web POS ve Admin Panelinin merkezinde konumlanır.
High-Level Mimari
Next.js App Router (Client) -> Service Katmanı (Inventory, POS, Checkout) -> SQLite & Drizzle ORM.
Frontend Architecture
Server-side rendering, Reusable UI tokens, optimistic cart updates, mobile-first duyarlı tasarım.
Backend Architecture
RESTful JSON API'ler, Transactional Idempotency, Drizzle Kit ORM migration altyapısı.
Modül Sınırları
Core, Catalog, Inventory, Orders, POS, Purchasing, Loyalty, AI Assistant bağımsız domainleri.
Database Mimarisi
Tüm para birimleri numeric(10,2) decimal, UTC timestamp, foreign key ve index optimizasyonu.
Ana Entity Listesi
users, customers, categories, brands, products, product_variants, warehouses, inventory, inventory_ledger, orders, pos_shifts.
ERD Tasarımı
Katalog -> Varyant -> Çoklu Depo Stok -> Stok Defteri -> Sipariş Kalemleri ilişkisel ağacı.
Inventory Transaction
Kullanılabilir Stok = Fiziksel Stok - Rezerve Stok. Her satış, iade ve sevk inventory_ledger'a işlenir.
Order Lifecycle
PENDING -> PAID -> PREPARING -> SHIPPED -> DELIVERED (veya CANCELLED/REFUNDED).
Payment Lifecycle
Adapter Pattern ile 3D Secure Kredi Kartı, Nakit Kasa ve Havale.
Purchase Lifecycle
Satın alma siparişi (PO) oluşturulur; mal kabul onaylandığında stoklar otomatik artırılır.
POS Terminal Mimarisi
Kasiyer vardiya açılışı, barkod tabancası okuma, askıya alma, karma ödeme ve termal satış fişi baskısı.
Müşteri CRM Mimarisi
Sadakat puanları, segmentasyon (VİP/AKTİF/KAYIP RİSKİ), iade geçmişi ve kişiye özel kampanyalar.
Sipariş & Belge Takibi
POS ve çevrimiçi siparişler tekil orderNumber iç belge numarasıyla izlenir; durum geçmişi audit_logs üzerinde tutulur.
Arama Mimarisi
Ürün adı, SKU, barkod ve varyant renklerinde tam metin arama ve Türkçe karakter desteği.
Bildirim Mimarisi
Sipariş onayı, kargo takip numarası ve kritik stok uyarıları için tekil olay motoru.
Güvenlik Mimarisi
SQL Injection koruması (parametrik sorgular), XSS filtreleri, güvenli HTTP başlıkları.
RBAC Yetki Modeli
Kasiyer sadece POS ekranına erişebilirken, depo şefi transfer ve sayım yetkisine sahiptir.
Audit Log Mimarisi
Fiyat ve stok güncellemelerinde kullanıcı kimliği, IP ve zaman damgasıyla değiştirilemez kayıt.
Cache Stratejisi
Next.js ISR ve HTTP Cache-Control ile hızlı katalog sunumu.
Background Worker
Otomatik kritik stok reorder kontrolleri ve zamanlanmış rapor üretimi.
Docker Konfigürasyonu
Multi-stage Dockerfile ve izole MySQL 8 veritabanı konteyner mimarisi.
Dev / Staging / Prod Ortamları
Environment variable ile yönetilen izole konfigürasyon.
CI/CD Pipeline
Type check -> Lint -> Build -> Database Push -> Healthcheck aşamaları.
Disaster Recovery & Backup
Günlük otomatik snapshot ve S3 uyumlu yedekleme planı.
Monitoring & Health Check
/api/health uç noktası ile veritabanı ve servis canlılık izlemesi.
SEO Teknik Mimarisi
Product, Organization, Breadcrumb JSON-LD şemaları, dinamik OG etiketleri.
AI Guardrails
AI analizleri yalnızca tavsiye üretir; kullanıcı onayı olmadan veri değişikliği yapılamaz.
Klasör Yapısı
Next.js App Router, /db şeması, /lib servisleri ve /components modüler mimarisi.
API Versioning
Standart JSON zarfı { success, data, error } ile öngörülebilir API yanıtları.
İsimlendirme Kuralları
Veritabanında snake_case, TypeScript'te camelCase, URL rotalarında kebab-case.
Kod Kalite Standartları
SOLID, DRY, Domain-Driven Design prensipleri.
Test Stratejisi
TypeScript derleme doğrulaması ve kritik sipariş/stok entegrasyon testleri.
Geliştirme Yol Haritası
FAZ 0'dan FAZ 12'ye kadar aşamalı ve doğrulanabilir teslimat planı.
MVP vs İleri Sürüm
MVP'de tam çalışan POS ve WMS; ileri sürümde gelişmiş analitik ve dış sistem entegrasyonları.
Architecture Decisions
- •Tekil Stok Defteri (Stock Ledger): Stok hareket bazlı takip edilerek denetim bütünlüğü sağlandı.
- •Next.js + MySQL Monolith: POS ve vitrinin senkron kalması için sıfır gecikmeli ortak ORM seçildi.
- •Merkezi Sipariş Defteri: POS ve çevrimiçi satışlar tek bir sipariş kaydı ve stok defterinde toplanır.
Development Readiness Checklist
- Veritabanı tabloları MySQL üzerinde oluşturuldu.
- Tuhafiye ürünleri, varyantları ve stokları tohumlandı.
- Web POS, Çoklu Depo ve e-Ticaret sepeti entegre edildi.
- Kural tabanlı AI asistanı devreye alındı.