# Guida Multi-Region — adiuvAI API

> Stato attuale: FastAPI containerizzata (docker-compose) su singolo VPS Hetzner in Europa.
> Obiettivo: ridurre la latenza per utenti fuori dall'Europa.

---

## Fase 1 — Ottimizzare Cloudflare (già in uso)

### 1.1 Argo Smart Routing

- **Dashboard → Traffic → Argo** — attivalo (~$5/mese + $0.10/GB)
- Usa i backbone privati Cloudflare invece dell'internet pubblico
- Riduce la latenza del 30-40% senza toccare nulla lato server
- Singolo cambiamento con miglior rapporto costo/beneficio

### 1.2 SSL/TLS

- **Dashboard → SSL/TLS → Overview** → mode **Full (Strict)** (non "Flexible", causa redirect loop)
- Abilita **TLS 1.3** (meno round-trip nell'handshake)
- Abilita **Early Hints** (103) in Speed → Optimization

### 1.3 Cache Rules

Di default Cloudflare non cachea le risposte API (Content-Type `application/json`). Per gli endpoint pubblici (es. `/api/v1/health`):

- **Dashboard → Caching → Cache Rules** → crea regola:
  - Match: `URI Path starts with /api/v1/health`
  - Action: Cache, Edge TTL 30s, Browser TTL 10s
- Lato codice: aggiungere header `Cache-Control: public, s-maxage=30` e `CDN-Cache-Control: public, max-age=30` all'health endpoint
- **NON** cacheate endpoint autenticati (il JWT rende ogni richiesta unica)

### 1.4 Response Compression

- **Dashboard → Speed → Optimization → Content Optimization**
- Abilita **Brotli** (più efficiente di gzip per payload JSON)
- Le risposte JSON vengono compresse automaticamente al transit

### 1.5 WebSocket

- **Dashboard → Network** → verifica che **WebSockets** sia ON (default nel piano Free)
- Il `/chat/stream` WebSocket viene proxato ma non cacheato
- Il keepalive di 30s che già avete mantiene la connessione viva attraverso Cloudflare

### 1.6 Tiered Cache (piano Pro+)

- **Dashboard → Caching → Tiered Cache** → attiva **Smart Tiered Caching**
- Cloudflare usa data center "upper-tier" come cache intermedia
- Riduce le hit al tuo origin server

### 1.7 Timeout

- **Dashboard → Network → WebSocket timeout**: aumenta se gli utenti hanno sessioni chat lunghe
- **Proxy Read Timeout**: default 100s, sufficiente per le LLM call (il tool loop ha cap 5 iterazioni)

---

## Fase 2 — Secondo nodo in US East

### Architettura target

```
                    ┌─── Cloudflare (Geo Steering) ───┐
                    │                                   │
           utenti EU/Africa                     utenti Americas
                    │                                   │
          ┌────────▼─────────┐              ┌──────────▼─────────┐
          │  VPS EU (attuale)  │              │   VPS US (nuovo)    │
          │  docker-compose    │              │   docker-compose    │
          │  app + PG primary  │              │   app + PG replica  │
          └────────┬──────────┘              └──────────┬──────────┘
                    │                                    │
                    └── PG streaming replication ────────┘
                        (async, read-only replica)
```

### Opzione A: Secondo VPS Hetzner (Ashburn) + Cloudflare Load Balancing

Estensione naturale del setup attuale — minimo cambiamento architetturale.

#### Step 1 — Provisioning del VPS US

1. Crea un VPS Hetzner in **Ashburn (us-east)** (stesse specs del nodo EU)
2. Setup identico: Docker, Docker Compose, git
3. Configura un **tunnel WireGuard** tra EU e US per il traffico DB (mai esporre PG sulla rete pubblica)

#### Step 2 — PostgreSQL Streaming Replication

**Sul PRIMARY (EU):**

1. Creare un utente replication:
   ```sql
   CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD '<strong_password>';
   ```
2. Creare un replication slot:
   ```sql
   SELECT pg_create_physical_replication_slot('replica_us_east');
   ```
3. Configurare `pg_hba.conf` per permettere connessioni dal VPS US:
   ```
   host replication replicator <US_VPS_WIREGUARD_IP>/32 scram-sha-256
   ```
4. Esporre la porta PG solo sull'IP WireGuard nel `docker-compose.yml`:
   ```yaml
   services:
     db:
       ports:
         - "10.0.0.1:5432:5432"  # solo interfaccia WireGuard
   ```

**Sul REPLICA (US):**

1. Base backup dal primary:
   ```bash
   docker run --rm \
     -v postgres_data:/var/lib/postgresql/data \
     pgvector/pgvector:pg16 \
     bash -c "pg_basebackup -h <PRIMARY_WG_IP> -U replicator \
              -D /var/lib/postgresql/data -Fp -Xs -P -R"
   ```
   Il flag `-R` crea automaticamente `standby.signal` e scrive `primary_conninfo` in `postgresql.auto.conf`.

2. Avviare PG in modalita replica (legge `standby.signal` e si connette al primary)

3. Verificare:
   - Sul primary: `SELECT * FROM pg_stat_replication;` (deve mostrare il replica)
   - Sul replica: `SELECT pg_is_in_recovery();` (deve restituire `t`)

#### Step 3 — Modifiche al codice FastAPI

Modifiche necessarie in `app/config/settings.py`:
- Aggiungere `DATABASE_READ_URL: str = ""` — URL del replica locale per le letture
- Aggiungere `REGION: str = "eu"` — identificativo regione per health check e observability

Modifiche in `app/db.py`:
- Creare un secondo engine `read_engine` che usa `DATABASE_READ_URL` (fallback a `DATABASE_URL` se vuoto)
- Esporre un `get_read_session()` dependency da usare nelle query read-only

Modifiche in `app/main.py`:
- L'health endpoint deve restituire `region` nel payload
- Aggiungere header `Cache-Control` / `CDN-Cache-Control` per il caching all'edge

Nelle route, per le query di sola lettura pesanti (es. ricerca, listing):
- Usare `db: AsyncSession = Depends(get_read_session)` invece di `get_session`
- Le scritture (auth, billing, update) continuano a usare `get_session` (→ primary EU)

#### Step 4 — Docker Compose per il nodo US

Creare un `docker-compose.replica.yml` (override) che:
- Sovrascrive le env dell'app con `DATABASE_READ_URL` verso il DB locale e `DATABASE_URL` verso il primary EU
- Imposta `REGION=us-east`
- Avvia PG in modalita replica (con `primary_conninfo` che punta al primary EU via WireGuard)

Il `.env` sul nodo US:
```env
DATABASE_URL=postgresql+asyncpg://postgres:<pass>@<PRIMARY_WG_IP>:5432/adiuvai
DATABASE_READ_URL=postgresql+asyncpg://postgres:postgres@db:5432/adiuvai
REGION=us-east
PRIMARY_DB_HOST=<PRIMARY_WG_IP>
REPLICATOR_PASSWORD=<strong_password>
# ... resto delle variabili (JWT_SECRET, STRIPE, LLM keys, etc.) identiche al nodo EU
```

Avvio: `docker compose -f docker-compose.yml -f docker-compose.replica.yml up -d`

#### Step 5 — Deploy CI multi-region

Estendere il workflow `.gitea/workflows/deploy.yaml` con un secondo job `deploy-us`:
- Identico a `deploy` ma con SSH verso il VPS US
- Usa `secrets.SSH_HOST_US`, `secrets.SSH_USER_US`, `secrets.SSH_KEY_US`
- Il comando di deploy usa `-f docker-compose.yml -f docker-compose.replica.yml`
- **NON** esegue `alembic upgrade head` — le migrazioni girano solo sul primary (il replica riceve le DDL via replication)

I due job `deploy` e `deploy-us` possono girare in parallelo (entrambi dipendono solo da `test`).

#### Step 6 — Cloudflare Geo Steering

1. **Dashboard → Traffic → Load Balancing** (piano Pro, ~$5/mese per pool)
2. Creare due **Origin Pools**:
   - `eu-pool`: origin = IP del VPS EU, health check = `GET /api/v1/health`
   - `us-pool`: origin = IP del VPS US, health check = `GET /api/v1/health`
3. Creare un **Load Balancer** su `api.adiuvai.com`:
   - Steering policy: **Geo**
   - EU/Africa → `eu-pool`
   - Americas → `us-pool`
   - Fallback: `eu-pool`
4. Impostare health monitor: `GET /api/v1/health`, interval 60s, timeout 5s
   - Se un nodo va giù, tutto il traffico va al nodo sano (automatic failover)

### Opzione B: Fly.io (alternativa più semplice, meno controllo)

Se preferisci evitare la gestione manuale di un secondo VPS:

1. Crea un `fly.toml` nella root del progetto API
2. `fly launch` — Fly rileva il Dockerfile e deploya
3. `fly regions add iad` — aggiunge US East (Ashburn)
4. Fly gestisce: routing anycast, health checks, TLS, auto-scaling
5. Il DB resta su Hetzner EU — Fly non risolve il problema del database, ma elimina tutta la gestione infrastrutturale dell'app layer
6. Costo: ~$5-15/mese per region (dipende dalle risorse)
7. Contro: meno controllo, vendor lock-in, il DB non ha replica locale

### Opzione C: Hetzner Cloud Load Balancer + geo DNS esterno

- Hetzner offre load balancer nativi, ma sono single-region (non cross-region)
- Non adatto per geo-routing, utile solo per HA nella stessa region

---

## Fase 3 — Terzo nodo in Asia (futuro)

Stessa procedura della Fase 2:
1. VPS Hetzner Singapore (o AWS ap-southeast-1)
2. Secondo PG replica con slot `replica_asia`
3. Terzo pool in Cloudflare Load Balancing con geo steering per Asia-Pacific
4. Terzo job `deploy-asia` nel CI

Da valutare solo quando il traffico dall'Asia lo giustifica.

---

## Sicurezza della rete tra i nodi

| Metodo | Pro | Contro |
|--------|-----|--------|
| **WireGuard** | Semplice, veloce, <1ms overhead, kernel-level | Setup manuale per nodo |
| **Hetzner vSwitch** | Zero config se entrambi su Hetzner | Solo stessa region |
| **Tailscale** | WireGuard gestito, zero config rete | Dipendenza esterna |
| **SSH tunnel** | Nessun software extra | Overhead maggiore, meno stabile |

**Raccomandazione**: WireGuard (o Tailscale per semplicita) tra tutti i nodi. Mai esporre PostgreSQL 5432 sull'IP pubblico.

---

## Considerazioni specifiche per adiuvAI

- **L'app e local-first**: la maggior parte delle operazioni (tasks, notes, projects) avviene in SQLite locale nell'Electron app. Il backend serve solo auth, chat streaming, cloud storage e billing. Questo significa che la latenza del backend impatta meno di quanto sembrerebbe.
- **WebSocket `/chat/stream`**: il geo steering porta l'utente al nodo piu vicino, ma la risposta LLM dipende dalla latenza verso OpenAI/Anthropic (non verso il tuo server). Il beneficio principale e nel tempo di handshake e nel primo token.
- **`_pending_states` in-memory per OAuth**: gia documentato come non scalabile su multi-worker. Con multi-region diventa critico — servira Redis condiviso o spostare lo state su DB.
- **JWT_SECRET deve essere identico** su tutti i nodi — un token emesso dal nodo EU deve essere validato dal nodo US.
- **Alembic migrations**: eseguire SOLO sul primary. Il replica riceve le DDL via streaming replication.

---

## Stima costi

| Componente | Costo mensile |
|------------|---------------|
| Argo Smart Routing | ~$5 + $0.10/GB |
| Cloudflare Load Balancing | ~$5/pool |
| VPS Hetzner US (CX22) | ~$5-10 |
| WireGuard | Gratis |
| **Totale Fase 1** | **~$5** |
| **Totale Fase 2** | **~$15-20** |