# 02 — Mimari, Repo ve Backend Entegrasyonu

> **AI'lere sorulacak:** Katman ayrımı doğru mu? API tasarımı yeterli mi? Güvenlik boşluğu görüyor musunuz?

**Versiyon:** 1.0 · **2026-07-05**

---

## 1. Katman diyagramı

```mermaid
flowchart TB
  subgraph client [Android İstemci]
    Shell[Native Shell]
    Launcher[App Launcher]
    DeviceAgent[Device Agent]
    NativeMod[Native Modüller]
    WebRuntime[WebView Runtime]
  end
  subgraph cloud [Emare Cloud]
    API[EmareTicket API]
    Web[Next.js Workspace]
    Store[app.emarecloud.tr]
    AI[AI Asistan]
  end
  Shell --> Launcher
  Shell --> DeviceAgent
  Launcher --> NativeMod
  Launcher --> WebRuntime
  Launcher --> Store
  Shell --> API
  WebRuntime --> Web
  DeviceAgent --> AI
  DeviceAgent --> API
```

---

## 2. Bileşen sorumlulukları

| Bileşen | Görev |
|---------|--------|
| **Shell** | Splash, login, bottom nav, tema |
| **Launcher** | `workspace.json` → app grid, deep link |
| **WebView runtime** | Mini-app URL + `auth-storage` enjeksiyonu |
| **Native modüller** | Inbox, calls, demo, NFC/OCR |
| **Device Agent** | AI komut → telefon aksiyonu |
| **Cloud API** | Auth, CRM, device registry, manifest |

---

## 3. Repo düzeni

### Hedef

```
Elyafgroup/
├── superapp/
│   ├── docs/           ← 5 ana MD (bu set)
│   ├── android/        ← Faz 0: legacy superapp taşınır
│   └── shared/schemas/
├── Mobile App/         ← Faz 1: modüller android/ içine
├── tenant-sites/superapp/   ← Web mağaza (canlı)
├── web/                ← Workspace entrypoints
└── src/EmareTicket.*   ← Backend
```

### Mevcut (geçiş)

| Bileşen | Path | Git |
|---------|------|-----|
| Superapp Android | `/Users/emre/Emare superapp` | ❌ Dışarı |
| Emare Asistan | `Mobile App/` | ✅ |
| Web mağaza | `tenant-sites/superapp/` | ✅ |

**Branch:** `feat/superapp/phaseN-açıklama` · aktif platform: `gece-otonom`

---

## 4. Veri akışları

### Giriş
`LoginActivity` → `POST /api/v1/auth/login-token` → `SessionManager` → `MainActivity`

### Web mini-app oturum
`localStorage.setItem('auth-storage', JSON)` — Zustand uyumlu; page start/finish'de tekrar enjekte

### Device komut (hedef)
AI/kullanıcı → `POST /api/v1/device/commands` → Agent → Policy → Execute → Audit

---

## 5. Auth & session

| Alan | Kullanım |
|------|----------|
| accessToken | Bearer API |
| refreshToken | Yenileme (plan) |
| userId, email, roles | UI + yetki |
| tenantSlug, tenantDomain | Multi-tenant |

**Standart:** Kritik path'lerde **OkHttp + JSONObject** (Gson/ProGuard riski).  
**Site API Key:** BuildConfig — repoya yazılmaz.

**WebView auth-storage şeması:**
```json
{
  "state": {
    "tokens": { "token": "...", "refreshToken": "..." },
    "user": { "id", "email", "firstName", "lastName", "roles": [] },
    "isAuthenticated": true,
    "isLoading": false
  }
}
```

---

## 6. API — mevcut endpoint'ler

**Base:** `https://aiasistan.emarecloud.tr/`

| Method | Path | Not |
|--------|------|-----|
| POST | `/api/v1/auth/login-token` | Login |
| POST | `/api/v1/onboarding/*` | Provision **eksik** |
| POST | `/api/v1/calls/ai-outbound` | Yanıt CallLog DTO — Gson değil |
| POST | `/api/site/v1` | Legacy fatura/arıza |
| GET | `/api/v1/updates/version` | OTA |

Inbox (Asistan): livechat, whatsapp, inbound-emails endpoint'leri.

---

## 7. API — planlanan (superapp)

```
GET  /api/v1/tenant/workspace-manifest
GET  /api/v1/superapp/catalog
POST /api/v1/device/register
POST /api/v1/device/commands
GET  /api/v1/device/commands/pending
POST /api/v1/device/audit
```

Feature key önerisi: `device_control`, `superapp_catalog`

---

## 8. Güvenlik ilkeleri

1. Token → EncryptedSharedPreferences / Keystore
2. WebView domain whitelist (`network_security_config`)
3. Device komut: tenant + user + deviceId binding
4. Root modül ayrı flavor; audit zorunlu
5. PII/token loglanmaz

---

## 9. Platform referansları

- Workspace manifest: `docs/workspaces/WORKSPACE_MANIFEST.md`
- Modül listesi: `Ortak Çalışma/moduller/modules.json`
- Ekosistem: `src/EmareTicket.AI/Resources/emare-ecosystem.json`
- AI actions: `docs/AI_ACTION_ENGINE.md`

---

## 10. AI'den istenen geri bildirim

1. Device API şeması yeterli mi? REST vs WebSocket?
2. Manifest tek kaynak mı, katalog ayrı mı kalmalı?
3. Auth refresh stratejisi öneriniz?
4. Multi-tenant device izolasyonu riskleri?

**Önceki:** [01-VIZYON-VE-KARARLAR.md](./01-VIZYON-VE-KARARLAR.md) · **Sonraki:** [03-MOBIL-ANDROID-ASISTAN.md](./03-MOBIL-ANDROID-ASISTAN.md)