# Mimari

## Üst düzey akış

Varsayılan (yerel tmux + tünel):

```
Browser (phone)
  |
  | HTTPS
  v
Cloudflare Quick Tunnel
  |
  | HTTP/WS
  v
Local Termbridge server
  |
  | PTY
  v
Tmux session
```

Doğrudan sandbox modu (Daytona, tünel yok):

```
Browser (phone)
  |
  | HTTPS
  v
Daytona preview link
  |
  | HTTP/WS
  v
Termbridge server (sandbox)
  |
  | PTY
  v
Tmux session (sandbox)
```

`--no-tunnel` ayarlandığında Termbridge, Cloudflare adımını atlar ve sağladığınız genel URL değerini kullanır.

## Bileşenler

### CLI süreci

- UI varlıklarını sunan HTTP sunucusunu başlatır.
- Terminal G/Ç'si için WebSocket sunucusunu başlatır.
- Bir veya daha fazla tmux oturumu (ya da Daytona PTY) oluşturur.
- Tek kullanımlık kullanım belirteçleri oluşturur.
- Etkinleştirildiğinde tüneli başlatır ve izler (bugün Cloudflare).
- Doğrudan sandbox modunda, Termbridge'i sandbox içinde başlatır ve paylaşım URL değerini bekler.

### Terminal arka ucu

- **tmux arka ucu**: Gerçek tuş girişleri ve çıktı için `node-pty` kullanarak tmux'ye bağlanır.
- **Daytona arka ucu**: Sandbox içinde Daytona PTY'leri kullanır.
- Tam renk desteği için `TERM=xterm-256color` ve `COLORTERM=truecolor` ayarlar.
- tmux için, UI'i temiz tutmak amacıyla tmux durum çubuğunu devre dışı bırakır.

### Terminal kayıt defteri

- Kullanılabilir terminal oturumlarını izler.
- UI için liste sağlar ve seçilen terminal kimliklerini doğrular.

### Kimlik doğrulama ve oturum

- Tek kullanımlık belirteç bir URL olarak yazdırılır ve bir QR koduna kodlanır.
- `GET /__tb/s/:token` belirteci kullanır ve bir çerez oturumu ayarlar.
- WebSocket bağlantıları geçerli bir oturum çerezi ve CSRF belirteci gerektirir.
- CSRF belirteci `GET /__tb/api/csrf` üzerinden alınır ve WebSocket sorgu parametresinde iletilir.

### Proxy modu

`--proxy <port>` aktarıldığında:
- Tüm termbridge yolları `/__tb/` önekinin altında yer alır
- `/__tb/` olmayan istekler hedef uygulamaya proxy edilir
- UI, Görünümler değiştiricisi aracılığıyla Terminal/Önizleme görünümlerini sunar
- Önizleme görünümü, `/` adresini gösteren bir iframe yükler
- HMR için WebSocket bağlantıları hedefe iletilir

### Güvenlik

- **CSRF koruması**: Siteler arası ele geçirmeyi önlemek için WebSocket yükseltmeleri CSRF belirteci gerektirir.
- **Girdi sınırları**: 64KB HTTP gövdesi, 1MB WebSocket mesajı, mesaj başına 64KB terminal girdisi.
- **Hız sınırlaması**: Belirteç kullanımı ve WebSocket bağlantıları için IP başına sınırlar.

## API uç noktaları

Proxy edilen uygulamalarla çakışmaları önlemek için tüm yollar `/__tb/` önekinin altında yer alır:

- `GET /__tb/healthz` - sistem durumu denetimi
- `GET /__tb/s/:token` - belirteç kullanımı → çerez → yönlendirme
- `GET /__tb/api/terminals` - terminalleri listeleme
- `GET /__tb/api/csrf` - WebSocket için CSRF belirteci alma
- `GET /__tb/api/config` - yapılandırma alma (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` - yeni bir tmux oturumu oluşturma
- `GET /__tb/app/*` - SPA yedeği
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` - terminal G/Ç'sini aktarma

Proxy modu etkinleştirildiğinde:
- `GET /` - proxy edilen uygulamaya yönlendirir (devre dışıysa `/__tb/app`)
- `* /*` - hedef uygulamaya proxy edilir

## WebSocket protokolü

İstemci -> sunucu:

```json
{ "type": "input", "data": "ls -la" }
{ "type": "resize", "cols": 120, "rows": 32 }
{ "type": "control", "key": "ctrl_c" }
```

Sunucu -> istemci:

```json
{ "type": "output", "data": "..." }
{ "type": "status", "state": "connected" }
```

## UI yığını

- Vite + TanStack Router
- xterm.js + Fit eklentisi + WebGL oluşturucu
- Mobil öncelikli düzen ve sabit giriş çubuğu
- Üstel beklemeyle otomatik yeniden bağlanma (en fazla 10 deneme)
- Bağlantı durumu göstergesi