Stack Tecnologico
Stack Tecnologico
Tutte le tecnologie, librerie e strumenti che compongono Il Carrubo, organizzati per categoria.
Backend
Il cuore del sistema è un server Node.js con Express come framework HTTP.
| Tecnologia | Versione | Ruolo |
|---|---|---|
| Node.js | >= 18 | Runtime JavaScript lato server |
| Express | 5.1.0 | Framework HTTP — routing, middleware, serving statico |
| pg | — | Driver nativo PostgreSQL per query dirette al database |
::: callout[note]
Express 5.x introduce il supporto nativo alle Promise nei route handler, eliminando la necessità di wrapper try/catch per gli errori asincroni.
:::
Database & Autenticazione
| Tecnologia | Ruolo |
|---|---|
| Supabase | Backend-as-a-Service basato su PostgreSQL |
| ↳ PostgreSQL | Database relazionale per tutti i dati applicativi |
| ↳ Supabase Auth | Autenticazione utenti con JWT, OAuth e magic link |
| ↳ Supabase Storage | Storage di file e immagini con URL firmati |
| ↳ Supabase Realtime | Subscriptions in tempo reale per aggiornamenti live |
| @supabase/supabase-js | Client JavaScript ufficiale per interagire con Supabase |
Frontend
L’interfaccia utente è costruita senza framework, per massima leggerezza e controllo.
| Tecnologia | Ruolo |
|---|---|
| Vanilla JavaScript | Logica client-side in ES6+ puro, senza framework |
| CSS3 | Stili personalizzati con supporto dark/light mode |
| Componenti shadcn-inspired | Componenti UI ispirati a shadcn/ui, adattati per vanilla JS |
| PWA | Progressive Web App con Service Worker, manifest e installabilità |
::: callout[tip]
Il frontend supporta nativamente il dark mode e il light mode, con switch automatico basato sulle preferenze di sistema dell’utente o commutabile manualmente.
:::
Integrazioni
Il Carrubo si integra con diversi servizi esterni per estendere le sue funzionalità.
| Libreria / Servizio | Ruolo | Dettagli |
|---|---|---|
| soap | Alloggiati Web | Comunicazione SOAP con il sistema della Questura per l’invio delle schedine alloggiati |
| mrz | Parsing documenti | Parsing della Machine Readable Zone (MRZ) da passaporti e carte d’identità |
| nodemailer | Invio email | Client SMTP per conferme prenotazione, welcome letter e comunicazioni agli ospiti |
| @axiomhq/js | Observability | Invio di log strutturati e metriche ad Axiom per monitoraggio e debugging |
| @ngrok/ngrok | Tunneling | Esposizione sicura del server locale su internet per test e demo |
| sitemap | SEO | Generazione automatica della sitemap XML per l’indicizzazione sui motori di ricerca |
| pdf-parse | Parsing PDF | Estrazione di testo e metadati da documenti PDF caricati |
| OCR.Space | OCR | Riconoscimento ottico dei caratteri da immagini di documenti |
| APITemplate.io | Generazione PDF | Creazione di PDF professionali da template (ricevute, welcome letter) |
| GitHub API | Storage | Archiviazione dei documenti scansionati su un repository GitHub |
Strumenti di sviluppo
| Strumento | Ruolo |
|---|---|
| nodemon | Riavvio automatico del server durante lo sviluppo al salvataggio dei file |
| blessed | Libreria per interfacce terminale avanzate (finestre, box, scroll) |
| blessed-contrib | Widget aggiuntivi per blessed (grafici, gauge, tabelle) |
| terser | Minificazione JavaScript per ottimizzare le dimensioni dei bundle in produzione |
| open | Apertura automatica del browser all’avvio del server di sviluppo |
Diagramma dello stack
graph TB
subgraph Frontend
A[HTML / CSS / Vanilla JS]
B[PWA / Service Worker]
end
subgraph Backend
C[Node.js]
D[Express 5.1]
E[Middleware]
end
subgraph Database
F[(Supabase PostgreSQL)]
G[Auth]
H[Storage]
end
subgraph Integrazioni
I[SOAP - Questura]
J[OCR.Space]
K[APITemplate.io]
L[Nodemailer SMTP]
M[GitHub API]
N[Axiom]
end
subgraph Dev Tools
O[nodemon]
P[blessed GUI]
Q[terser]
end
A --> D
B --> D
D --> F
D --> G
D --> H
D --> I
D --> J
D --> K
D --> L
D --> M
D --> N
O -.-> C
P -.-> C
Q -.-> A
Prossimi passi
| Sezione | Descrizione |
|---|---|
| Struttura del Progetto | Organizzazione dei file e delle directory |
| Architettura del Sistema | Diagrammi e flussi architetturali |