# Αρχιτεκτονική

## Ροή υψηλού επιπέδου

Προεπιλογή (τοπικό tmux + σήραγγα):

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

Άμεση λειτουργία sandbox (Daytona, χωρίς σήραγγα):

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

Όταν οριστεί το `--no-tunnel`, το Termbridge παραλείπει το Cloudflare και χρησιμοποιεί το δημόσιο URL που δώσατε.

## Στοιχεία

### Διαδικασία CLI

- Εκκινεί τον διακομιστή HTTP που εξυπηρετεί τα στοιχεία UI.
- Εκκινεί τον διακομιστή WebSocket για είσοδο/έξοδο τερματικού.
- Δημιουργεί μία ή περισσότερες συνεδρίες tmux (ή PTY Daytona).
- Εκδίδει διακριτικά μίας χρήσης για εξαργύρωση.
- Εκκινεί και παρακολουθεί τη σήραγγα όταν είναι ενεργοποιημένη (Cloudflare προς το παρόν).
- Στην άμεση λειτουργία sandbox, εκκινεί το Termbridge μέσα στο sandbox και περιμένει το κοινόχρηστο URL.

### Backend τερματικού

- **Backend tmux**: Χρησιμοποιεί το `node-pty` για σύνδεση στο tmux και υποστηρίζει πραγματικές πληκτρολογήσεις και έξοδο.
- **Backend Daytona**: Χρησιμοποιεί PTY Daytona μέσα σε sandbox.
- Ορίζει τα `TERM=xterm-256color` και `COLORTERM=truecolor` για πλήρη υποστήριξη χρωμάτων.
- Για tmux, απενεργοποιεί τη γραμμή κατάστασης tmux ώστε να διατηρεί καθαρό το UI.

### Μητρώο τερματικών

- Παρακολουθεί τις διαθέσιμες συνεδρίες τερματικού.
- Παρέχει λίστα για το UI και επικυρώνει τα επιλεγμένα αναγνωριστικά τερματικών.

### Έλεγχος ταυτότητας και συνεδρία

- Το διακριτικό μίας χρήσης εμφανίζεται ως URL και κωδικοποιείται σε κώδικα QR.
- Το `GET /__tb/s/:token` εξαργυρώνει το διακριτικό και ορίζει μια συνεδρία cookie.
- Οι συνδέσεις WebSocket απαιτούν έγκυρο cookie συνεδρίας και διακριτικό CSRF.
- Το διακριτικό CSRF ανακτάται μέσω του `GET /__tb/api/csrf` και περνά ως παράμετρος query του WebSocket.

### Λειτουργία διακομιστή μεσολάβησης

Όταν περνά το `--proxy <port>`:
- Όλες οι διαδρομές του termbridge βρίσκονται κάτω από το πρόθεμα `/__tb/`
- Τα αιτήματα που δεν είναι `/__tb/` προωθούνται στην εφαρμογή-στόχο
- Το UI εμφανίζει τις προβολές Terminal/Preview μέσω του εναλλάκτη Views
- Η προβολή Preview φορτώνει ένα iframe που δείχνει στο `/`
- Οι συνδέσεις WebSocket για HMR προωθούνται στον στόχο

### Ασφάλεια

- **Προστασία CSRF**: Οι αναβαθμίσεις WebSocket απαιτούν διακριτικό CSRF για την αποτροπή παραβίασης από άλλη προέλευση.
- **Όρια εισόδου**: σώμα HTTP 64KB, μήνυμα WebSocket 1MB, είσοδος τερματικού 64KB ανά μήνυμα.
- **Περιορισμός ρυθμού**: Όρια ανά IP για την εξαργύρωση διακριτικών και τις συνδέσεις WebSocket.

## Καταληκτικά σημεία API

Όλες οι διαδρομές βρίσκονται κάτω από το πρόθεμα `/__tb/` για την αποφυγή διενέξεων με εφαρμογές που προωθούνται μέσω διακομιστή μεσολάβησης:

- `GET /__tb/healthz` - έλεγχος υγείας
- `GET /__tb/s/:token` - εξαργύρωση διακριτικού → cookie → ανακατεύθυνση
- `GET /__tb/api/terminals` - λίστα τερματικών
- `GET /__tb/api/csrf` - λήψη διακριτικού CSRF για WebSocket
- `GET /__tb/api/config` - λήψη ρυθμίσεων (proxyPort, devProxyUrl)
- `POST /__tb/api/terminals` - δημιουργία νέας συνεδρίας tmux
- `GET /__tb/app/*` - εφεδρική διαδρομή SPA
- `WS /__tb/ws/terminal/:terminalId?csrf=<token>` - ροή εισόδου/εξόδου τερματικού

Όταν είναι ενεργοποιημένη η λειτουργία διακομιστή μεσολάβησης:
- `GET /` - ανακατεύθυνση στην εφαρμογή μέσω διακομιστή μεσολάβησης (ή `/__tb/app` αν είναι απενεργοποιημένη)
- `* /*` - προώθηση στην εφαρμογή-στόχο μέσω διακομιστή μεσολάβησης

## Πρωτόκολλο WebSocket

Πελάτης -> διακομιστής:

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

Διακομιστής -> πελάτης:

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

## Στοίβα UI

- Vite + TanStack Router
- xterm.js + πρόσθετο Fit + μηχανή απόδοσης WebGL
- Διάταξη πρώτα για κινητά, με σταθερή γραμμή εισόδου
- Αυτόματη επανασύνδεση με εκθετική καθυστέρηση (έως 10 προσπάθειες)
- Ένδειξη κατάστασης σύνδεσης