Struttura del Progetto

Panoramica completa dell’organizzazione dei file e delle directory de Il Carrubo.

Albero del progetto

il-carrubo-edit/
├── server.js              # Backend principale (3.200+ righe)
├── middleware.js           # Vercel Edge Middleware
├── server-gui.js           # GUI terminale (blessed)
├── api/
│   ├── index.js            # Handler serverless Vercel
│   ├── ping-db.js          # Health check database
│   └── routes/             # Router RESTful v1
├── cli/
│   ├── carrubo.js          # CLI principale
│   └── api.js              # Wrapper API per CLI
├── public/
│   ├── *.html              # Pagine frontend (20+)
│   ├── script.js           # Logica client-side principale
│   ├── assets/             # CSS, JS, fonts, immagini
│   ├── scanner/            # Modulo scanner MRZ
│   ├── ad/dashboard/       # Admin dashboard
│   └── icons/              # Icone PWA
├── data/                   # Dati statici (comuni ISTAT, stati)
├── pdftemplate/            # Template PDF
├── logs/                   # Log di sessione
├── ssl/                    # Certificati SSL (opzionale)
└── docs-site/              # Questa documentazione

File principali

server.js — Backend principale

Il cuore del sistema. Un file monolitico di oltre 3.200 righe che contiene:

• Inizializzazione dell’app Express e dei middleware
• Tutti i 46 endpoint API (CRUD prenotazioni, ospiti, camere, tariffe, ecc.)
• Logica di integrazione con servizi esterni (SOAP, OCR, PDF, email)
• Gestione dell’autenticazione e dell’autorizzazione
• Error handling centralizzato
• Scheduled tasks e job ricorrenti

::: callout[note]
La scelta monolitica è intenzionale: semplifica il deployment, il debugging e la comprensione del flusso per un singolo sviluppatore. Le route API v1 sono in fase di estrazione progressiva nel modulo api/routes/.
:::

middleware.js — Edge Middleware

Middleware eseguito a livello di Vercel Edge, prima che la richiesta raggiunga il server Node.js. Responsabile di:

• Modalità manutenzione — restituisce una pagina di manutenzione se attivata
• Feature flags — abilita/disabilita funzionalità in base alla configurazione
• Redirect — gestisce redirect e rewrite delle URL

server-gui.js — GUI Terminale

Interfaccia terminale interattiva basata su blessed e blessed-contrib. Mostra in tempo reale:

• Log delle richieste HTTP colorate per status code
• Grafici di utilizzo CPU e memoria
• Stato delle connessioni al database
• Contatori di richieste e errori

Directory

api/ — Serverless & Router

cli/ — Interfaccia a riga di comando

public/ — Frontend

La directory public/ contiene tutto il frontend, servito staticamente da Express.

::: callout[tip]
Il frontend utilizza una struttura a pagine singole (multi-page app), dove ogni pagina HTML è indipendente. Lo script.js principale è condiviso tra le pagine per la logica comune.
:::

data/ — Dati statici

Contiene file JSON con dati di riferimento utilizzati dall’applicazione:

• Comuni ISTAT — elenco completo dei comuni italiani con codici ISTAT e province
• Stati — elenco degli stati del mondo con codici ISO e nazionalità
• Codici documento — tipologie di documenti d’identità accettati

pdftemplate/ — Template PDF

Template HTML utilizzati per la generazione di documenti PDF tramite APITemplate.io:

• Ricevute di pagamento
• Welcome letter per gli ospiti
• Report di riepilogo

logs/ — Log di sessione

Directory per i file di log generati durante l’esecuzione del server. I log includono:

• Richieste HTTP con timestamp, metodo, path e status code
• Errori con stack trace completo
• Eventi di sistema (avvio, shutdown, connessioni)

::: callout[note]
La directory logs/ è inclusa nel .gitignore. I log in produzione vengono inviati ad Axiom per la persistenza e l’analisi.
:::

ssl/ — Certificati SSL

Directory opzionale per i certificati SSL quando si esegue il server in HTTPS locale:

• cert.pem — Certificato pubblico
• key.pem — Chiave privata

docs-site/ — Documentazione

Questa stessa documentazione, costruita con docmd.io. Contiene tutti i file Markdown, la configurazione del sito e le risorse statiche.

Diagramma delle dipendenze

Prossimi passi