Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
58 lines (49 loc) · 2.66 KB

ARCHITECTURE.md

File metadata and controls

58 lines (49 loc) · 2.66 KB
Raw

Mimari

KBS-Sync, veriyi otelin ağı içinde tutan üç istemcili bir sistemdir.

flowchart LR
  Mobile["Android MRZ uygulaması"]
  LAN["Agent TLS API :8443"]
  Store["Şifreli SQLite\nmerkezi arşiv + kuyruk"]
  Loopback["Agent loopback API :8080"]
  Extension["Chrome MV3 eklentisi"]
  Portal["KBS portalı"]

  Mobile -->|"eşleştirme + pinned TLS"| LAN
  LAN --> Store
  Store --> Loopback
  Loopback <-->|"HTTP + WS protocol 4"| Extension
  Extension -->|"session / tab / kbs.api primitives"| Portal
Loading

Bileşen sınırları

  • apps/id-scanner: Görüntüyü cihazda işler; kimlik görselini saklamaz. MRZ sonucunu eşleştirilmiş agent'a aktarır ve yerel arşivini agenttaki merkezi kayıtlardan günceller.
  • agent: Kuyruklar, FSM orkestrasyon, eşleştirme/gözlem/reconcile kuralları ve kalıcı merkezi tarama arşivi burada yaşar (internal/orchestrator, internal/kbs). Canlı kuyruktan kaldırılan scan silinmez; arşivlenir. KBS satır kimliği (konaklayanId) check-in sırasında agent tarafından yakalanır ve yalnız agent tarafında saklanır; telefona veya eklentiye yansıtılmaz. 127.0.0.1:8080 eklenti yönetim API'si + browser bridge; 0.0.0.0:8443 mobil TLS API'si.
  • extension: Tarayıcıya bağlı primitifler (session.probe / session.ensure / session.logout / tab.ensure / tab.navigate / kbs.api) ve yönetim UI. Karar vermez; agent state'ini gösterir ve operatör eylemlerini agent mutation veya command'larına dönüştürür. Köprü sözleşmesi: BROWSER_BRIDGE_PROTOCOL_V4.md. Sahipli KBS sekmesi pinlenir ve autoDiscardable: false ile Memory Saver discard'ına kapatılır. Kuyrukta iş varken agent 3 dakikada bir session.probe atar (login yok); kuyruk son işten sonra iki dakika boşsa agent session.logout ister.

Güven sınırları

LAN portunun tüm arayüzlerde dinlemesi tasarım gereğidir; istemci sertifika sabitleme ve cihaz bearer tokenıyla doğrulanır. Yönetim/kimlik bilgisi uçları yalnız loopback'tedir. Bu sınırlar değiştirilirken tehdit modeli, testler ve veri güvenliği belgesi birlikte güncellenmelidir.

Agent, eklenti ve mobil uygulama ayrı sürüm alanlarına sahip olsa da yayın sürümünün tek kaynağı kökteki VERSION dosyasıdır. Bağlantı protokolü için mobile/COMPANION_API.md, köprü için BROWSER_BRIDGE_PROTOCOL_V4.md, şemalar için tek kaynak olarak agent/contracts/companion-v4/ kullanılır.

Merkezi arşiv yaşam döngüsü ve mobil replikasyon ayrıntıları: CENTRAL_SCAN_ARCHIVE.md.