1. Contesto del progetto (READ FIRST)

Stiamo costruendo un sistema di controllo remoto composto da:

Windows Client (Electron)
        ⇅ WebSocket (control-plane)
VPS Signaling Server (Node.js / TS)
        ⇅ WebSocket
Android Tablet Agent (Kotlin)


⚠️ IMPORTANTE

Il VPS NON trasporta video/audio/input.

Il VPS serve SOLO per:

autenticazione

signaling

presence (online/offline)

autorizzazione connessioni

In fasi successive, il traffico media passerà via WebRTC P2P/TURN (NON in Fase 1).

2. Stack tecnologico (decisioni definitive)
Linguaggi

TypeScript ovunque possibile

server: Node.js + TypeScript

windows: Electron + TypeScript

shared: TypeScript

Android: Kotlin (fuori scope TS)

Scelte chiave (NON cambiare senza chiedere)

Client Windows: Electron

Protocollo: WebSocket + JSON tipizzato

Condivisione tipi: pacchetto shared/protocol

Stato: in-memory per Fase 1 (DB arriverà dopo)

Auth Fase 1: seed user + pairingKey (MVP)

3. Modalità operativa tablet (definitiva)

Tablet Android:

sempre in ascolto

ForegroundService sempre attivo

MediaProjection verrà avviata in Fase 2

Connessioni in ingresso:

SEMPRE con accettazione manuale

notifica Android con “Accetta / Rifiuta”

⚠️ Non implementare:

auto-accept

connessioni silenziose

bypass dei permessi Android

4. Fase attuale del progetto
✅ Fase 1 — Control-plane ONLY

In questa fase:

❌ NIENTE WebRTC

❌ NIENTE MediaProjection

❌ NIENTE streaming

❌ NIENTE input remoto

✔️ SOLO:

WebSocket server

login client

register agent

device list

connect_request

accept / deny / expired

Se una PR introduce WebRTC o video → È SBAGLIATA

5. Protocollo di comunicazione

Tutti i messaggi:

{
  "v": 1,
  "type": "...",
  "requestId": "...",
  "...": "..."
}


I tipi sono definiti in:

/shared/protocol


⚠️ Regole:

Non inventare campi fuori dai tipi condivisi

Non usare stringhe “magiche”

Se serve un nuovo messaggio → aggiornare shared/protocol

6. Regole di sviluppo per Codex
Come lavorare

Ogni task = UNA PR

PR piccole, focalizzate

Niente “mega commit”

Ogni PR DEVE includere:

Codice funzionante

Logging minimo (no spam)

Error handling (no crash)

Checklist “come testare manualmente”

NON fare:

refactor non richiesti

miglioramenti “creativi”

cambiare stack

anticipare fasi future

7. Stato & persistenza (Fase 1)

Tutto in memoria

Restart server = stato perso (OK per MVP)

Nessun database obbligatorio ora

Strutture tipiche:

devicesById

sessionsById

clientSessionsByWs

8. Sicurezza (livello attuale)

Fase 1 = MVP controllato

Seed user + password in env

PairingKey in env

TLS solo in VPS (non locale)

⚠️ Non implementare:

hashing avanzato

JWT

refresh token

OAuth

Arriveranno in Fase 3.

9. Error handling (obbligatorio)

Su errore:

{
  "v": 1,
  "type": "error",
  "requestId": "...",
  "code": "UNAUTHORIZED | BAD_REQUEST | NOT_FOUND | CONFLICT | DEVICE_OFFLINE",
  "message": "human readable"
}


Mai crashare il server

Mai lasciare una promise non gestita

10. Naming e stile

camelCase per JSON

kebab-case per file

TypeScript strict

No any salvo motivazione

11. Test mindset

Ogni feature deve essere:

testabile via CLI o WS

osservabile via log

verificabile senza UI (se possibile)

Se non è testabile → probabilmente è sbagliata.

12. Frase guida del progetto

“Il VPS coordina, non guarda.
Il tablet decide, non subisce.
Il client controlla, non buca.”

13. In caso di dubbio

Se una decisione:

tocca sicurezza

cambia protocollo

anticipa WebRTC

rompe compatibilità

👉 FERMATI e chiedi prima.