Architettura
Overview

Architettura del Sistema

Il Carrubo segue un’architettura client-server monolitica con Supabase come backend-as-a-service per database, autenticazione e storage.

Panoramica

Il sistema è composto da tre layer principali:

Frontend — Pagine HTML statiche servite da Express con logica client-side in vanilla JavaScript
Backend — Server Express monolitico che gestisce API REST, integrazioni esterne e logica di business
Database — Supabase (PostgreSQL) per persistenza, autenticazione e real-time subscriptions

Diagramma di sistema

graph TB subgraph Client A[Browser / PWA] end subgraph Server["Express Server"] B[Route Handler] C[Middleware] D[Auth] end subgraph Database E[(Supabase PostgreSQL)] end subgraph Servizi Esterni F[Questura SOAP / Alloggiati Web] G[OCR.Space Scansione documenti] H[APITemplate.io Generazione PDF] I[GitHub API Storage documenti] L[SMTP Invio email] M[Axiom Observability] end A -->|HTTP / REST| C C -->|Auth check| D D -->|Autorizzato| B B -->|SQL / Client| E B -->|SOAP| F B -->|REST| G B -->|REST| H B -->|REST| I B -->|SMTP| L B -->|REST| M

Moduli principali

Il backend è organizzato in pochi file chiave, ciascuno con una responsabilità specifica:

Modulo	File	Descrizione
Backend principale	`server.js`	Cuore del sistema: 3.200+ righe che includono tutte le route API, la logica di business, le integrazioni esterne e la gestione degli errori. File monolitico che contiene l’intera logica server-side.
Edge Middleware	`middleware.js`	Middleware Vercel Edge che intercetta le richieste prima che raggiungano il server. Gestisce la modalità manutenzione, i feature flags e i redirect.
Serverless Handler	`api/index.js`	Adapter per il deploy serverless su Vercel. Wrappa l’app Express in un handler compatibile con le Vercel Serverless Functions.
Router API v1	`api/routes/`	Router RESTful modulare per le API versionate (`/api/v1/...`). Separa le route in file dedicati per risorsa.
GUI Terminale	`server-gui.js`	Interfaccia terminale basata su `blessed` e `blessed-contrib`. Mostra log in tempo reale, grafici di utilizzo e stato delle connessioni.

Flusso di autenticazione

Il Carrubo supporta due modalità di autenticazione, utilizzabili in alternativa:

flowchart TD A[Richiesta in arrivo] --> B{Header presente?} B -->|x-api-key| C[Verifica API Key] B -->|Authorization: Bearer| D[Verifica token Supabase] B -->|Nessuno| E[❌ 401 Unauthorized] C -->|Valida| F[✅ Accesso consentito] C -->|Non valida| E D -->|Token valido| F D -->|Token scaduto/invalido| E

Ciclo di vita di una richiesta

Ogni richiesta HTTP attraversa una pipeline ben definita prima di raggiungere il route handler:

sequenceDiagram participant C as Client participant E as Edge Middleware participant A as Auth Middleware participant R as Route Handler participant D as Database C->>E: HTTP Request E->>E: Controlla modalità manutenzione E->>E: Valuta feature flags E->>A: Inoltra richiesta A->>A: Verifica API Key o Bearer Token alt Non autorizzato A-->>C: 401 Unauthorized end A->>R: Richiesta autenticata R->>D: Query Supabase D-->>R: Risultato R-->>C: JSON Response

Dettaglio dei passaggi

Edge Middleware (`middleware.js`)

Intercetta tutte le richieste a livello di edge (Vercel). Controlla se il sistema è in modalità manutenzione e valuta i feature flags per abilitare o disabilitare funzionalità specifiche.

Autenticazione

Il middleware di autenticazione verifica la presenza e la validità dell’header x-api-key o Authorization: Bearer. Le richieste non autenticate ricevono un 401 Unauthorized.

Route Handler

La richiesta autenticata viene instradata al handler corretto in base al metodo HTTP e al path. Il handler esegue la logica di business, interagisce con il database e, se necessario, con i servizi esterni.

Risposta

Il handler restituisce una risposta JSON con il codice di stato appropriato. Gli errori vengono catturati dal middleware di error handling e restituiti in un formato consistente.

Prossimi passi

Sezione	Descrizione
Stack Tecnologico	Tecnologie e librerie utilizzate
Struttura del Progetto	Organizzazione dei file e delle directory
API Reference	Documentazione completa dei 46 endpoint