# Sistem Mimarisi

## Amaç

Telegram oyunu, PWA, Android ve iOS uygulamaları aynı kullanıcı, ekonomi, ledger ve yönetim ayarlarını kullanır. İstemciler görsel katmandır; kazanç üzerinde otorite API'dedir.

```mermaid
flowchart LR
  TG[Telegram Mini App] --> API[OnlyCoin HTTP API]
  PWA[Installable PWA] --> API
  AND[Android WebView] --> API
  IOS[iOS WKWebView] --> API
  WEB[Public Website] --> API
  ADM[Admin Panel] --> API

  API --> AUTH[Identity & Session]
  API --> GAME[Tap / Energy / Auto Engine]
  API --> ECON[VIP / Quest / Wheel / Referral]
  API --> LEDGER[Double-Entry Ledger]
  API --> AUDIT[Admin Audit]
  LEDGER --> DB[(SQLite MVP)]
  GAME --> DB
  ECON --> DB
  AUTH --> DB
  AUDIT --> DB
```

## İstek akışı

### Tap

```mermaid
sequenceDiagram
  participant C as İstemci
  participant A as API
  participant G as Game Engine
  participant L as Ledger
  participant D as DB

  C->>A: POST /api/game/tap + Idempotency-Key
  A->>A: Oturum + rate limit doğrula
  A->>G: count, user, server time
  G->>D: Enerjiyi zamanla uzlaştır
  G->>G: VIP ve booster ile ödülü hesapla
  G->>L: Reward pool -> User OC_POINTS
  L->>D: Transaction + iki entry + balance
  G->>D: Tap event + quest progress
  A-->>C: Doğrulanmış bakiye ve enerji
```

### OC_POINTS → OC_TOKEN

```mermaid
sequenceDiagram
  participant U as Kullanıcı
  participant API
  participant CFG as Admin Config
  participant L as Ledger
  participant DB

  U->>API: points + Idempotency-Key
  API->>CFG: enabled, rate, min, daily limit, launch lock
  API->>L: User points -> Points sink
  API->>L: Token treasury -> User token
  L->>DB: Atomik çift ledger işlemi
  API-->>U: tokensReceived + yeni bakiyeler
```

## Veri kaynağı

MVP'de SQLite kullanılır:

- Harici paket olmadan anında çalışır.
- WAL ve `BEGIN IMMEDIATE` ile yarış koşullarını sınırlar.
- Tek node dağıtım için uygundur.

Üretim ölçeğinde önerilen geçiş:

- PostgreSQL: ledger ve kalıcı domain verisi
- Redis: global rate limit, kısa süreli cache, leaderboard projection
- Durable queue: reklam/store webhook ve async işler
- Object storage: rapor ve dışa aktarma

## Bounded context'ler

- Identity & Sessions
- User Game State
- Tap & Energy
- Automatic Earnings
- VIP & Boosters
- Wheel
- Quests
- Referrals
- Leaderboard
- OC_POINTS/OC_TOKEN Ledger
- Conversion
- Admin & Audit

## Tek kod tabanı / çok kanal

Mobil uygulamalar web UI'ı güvenli bir native shell içinde açar. Böylece:

- Aynı ekranlar ve ekonomi kuralları
- Tek yayınlanan web bundle
- Telegram ve native uygulamalarda eşit davranış
- Hızlı güncelleme

Mağaza üretim sürümünde native billing, attestation, push ve deep-link köprüleri ayrıca eklenir.
