feat: land dashboard groundwork

DASH.MD

@@ -0,0 +1,93 @@
+# Gradio Tunnel Dashboard (studio progetto)
+
+Questo repository contiene una proposta di studio per un servizio Linux che:
+
+- **scansiona le porte in uso** sul server (inclusi i servizi Docker);
+- **mostra i risultati in una dashboard**;
+- **permette di selezionare un servizio/porta** e **attivare un tunnel** basato su [gradio-tunneling](https://github.com/arkohut/gradio-tunneling);
+- **espone l'URL del tunnel in dashboard**, con controlli per **mantenere** o **spegnere** il tunnel e liberare la risorsa.
+
+## Obiettivo del progetto
+
+Costruire un servizio che renda semplice e sicuro l'esposizione temporanea di servizi locali (es. container Docker) tramite tunnel, con un'interfaccia web centralizzata.
+
+## Architettura proposta
+
+### 1) Scanner delle porte
+
+- **Input**: porte in ascolto sul server (TCP/UDP), con informazioni su processo, PID, utente.
+- **Fonti consigliate**:
+  - `ss -ltnp` / `ss -lunp` per porte e processi.
+  - Docker: `docker ps` + `docker inspect` per mappature porte/servizi.
+- **Output**: lista normalizzata con:
+  - porta, protocollo, PID/processo,
+  - container (se applicabile),
+  - metadati (nome servizio, descrizione, tag).
+
+### 2) Service registry (modello dati)
+
+- **Store**: SQLite o PostgreSQL.
+- **Entità principali**:
+  - `Service` (nome, porta, protocollo, tipo, metadata)
+  - `Tunnel` (service_id, status, public_url, created_at, updated_at)
+
+### 3) Orchestratore Tunnel
+
+- **Driver**: integrazione con `gradio-tunneling`.
+- **Funzioni**:
+  - `start_tunnel(service)`
+  - `stop_tunnel(tunnel)`
+  - `health_check(tunnel)`
+- **Process supervision**:
+  - `systemd` (service unit) oppure job manager interno (process/thread pool).
+- **Persistence**:
+  - mantenere stato e URL pubblico nel DB.
+
+### 4) Dashboard web
+
+- **Funzionalità**:
+  - elenco porte/servizi disponibili
+  - filtri (per container, protocollo, status tunnel)
+  - azioni: avvia/termina tunnel
+  - mostra URL pubblico del tunnel con pulsante copia
+- **Stack possibili**:
+  - Backend: FastAPI/Flask
+  - Frontend: React/Vue, oppure UI server-side (Jinja2) o Gradio stesso
+
+### 5) Sicurezza e policy
+
+- Whitelist di porte consentite.
+- Autenticazione (OAuth, basic auth o SSO).
+- Audit log per avvio/stop tunnel.
+- Rate limiting per creare tunnel.
+
+## Flusso operativo (happy path)
+
+1. Scanner rileva porte attive e aggiorna il registry.
+2. L'utente apre la dashboard e seleziona un servizio.
+3. Il backend avvia `gradio-tunneling` sulla porta selezionata.
+4. L'URL pubblico del tunnel viene visualizzato in dashboard.
+5. L'utente può interrompere il tunnel e liberare la risorsa.
+
+## Milestone suggerite
+
+1. **MVP scanner**: lista porte + metadati base.
+2. **MVP dashboard**: tabella + pulsanti avvio/stop.
+3. **Tunnel orchestration**: integrazione `gradio-tunneling`.
+4. **Stabilità**: gestione processi, retry, health checks.
+5. **Security**: auth + policy + audit.
+
+## Note implementative
+
+- Per Docker: associare porta -> container tramite inspect o naming convention.
+- Prevedere un layer di caching per evitare scansioni continue troppo costose.
+- In caso di reboot, ripristinare lo stato dei tunnel o marcarli come inattivi.
+
+## Prossimi passi
+
+Se vuoi, posso:
+
+- generare una struttura iniziale del progetto (backend + frontend);
+- creare un prototipo funzionante con API di scansione e avvio tunnel;
+- aggiungere un esempio di integrazione con `gradio-tunneling`;
+- scrivere i container Docker per sviluppo locale.