Stack, domini, livelli e organizzazione del codice
Architettura
Questa pagina descrive l'architettura tecnica di Xedul. È rivolta a chi sviluppa sul prodotto o ne valuta l'impianto, non all'utente finale.
Stack
| Livello | Tecnologia |
|---|---|
| Frontend | Next.js 15 con App Router, React 19, TypeScript 5.8 |
| Stile | Tailwind CSS con design system a token |
| Stato | React Query per i dati remoti, store leggero per lo stato di interfaccia |
| Backend | Supabase: PostgreSQL, autenticazione, tempo reale, archiviazione |
| Autenticazione | Supabase Auth con controllo accessi basato sui ruoli |
| Tempo reale | Sottoscrizioni Supabase Realtime con caching |
| Internazionalizzazione | `next-intl` con cambio lingua dinamico |
Struttura del repository
Xedul/ ├── app-web/ applicazione Next.js │ └── src/ │ ├── app/ route App Router │ ├── domains/ logica di dominio │ ├── infrastructure/ API, database, tempo reale, provider │ ├── shared/ componenti, hook e utilità riusabili │ ├── translations/ file di traduzione │ └── types/ definizioni TypeScript ├── integrations/ add-on Gmail e Outlook, manifest ├── supabase/ configurazione e migrazioni ├── tooling/ lint, script di repository └── Doc/ documentazione interna
Architettura a domini
La logica di business è organizzata per dominio, non per tipo di file. Ogni dominio raccoglie ciò che serve al proprio ambito: tipi, hook, chiamate API, componenti.
I domini presenti includono autenticazione, clienti, contatti, pratiche, attività, calendario, documenti, commenti, notifiche, promemoria, organizzazione, utenti, stati, chat e i due domini di integrazione email.
La conseguenza pratica: aggiungere una funzionalità a un'area tocca quasi sempre una sola cartella di dominio, invece di propagarsi su cinque cartelle organizzate per tipo.
Il livello infrastrutturale
Sotto i domini sta l'infrastruttura, che isola il resto dell'applicazione dai dettagli tecnici:
- Controller API — separano la logica di business dai gestori di route.
- Livello database — accesso ai dati con pattern repository e tipizzazione.
- Composizione dei provider — gestione dello stato applicativo e dei contesti React.
- Sistema in tempo reale — sincronizzazione delle modifiche con caching, per evitare di rifare le stesse richieste.
Sistema di tipi a livelli
Xedul mantiene la sicurezza dei tipi dal database fino all'interfaccia, distinguendo livelli con responsabilità diverse:
| Livello | Ruolo |
|---|---|
| Tipi database | Schema e operazioni sul database |
| Tipi di dominio | Logica di business |
| Tipi UI | Proprietà dei componenti e stato dell'interfaccia |
| Tipi adapter | Trasformazione dati e integrazioni esterne |
| Tipi branded | Identificatori tipizzati, per non confondere due ID diversi |
I tipi branded meritano una nota: impediscono a livello di compilazione di passare l'identificativo di un cliente dove ne serve uno di pratica. È un errore che a runtime sarebbe silenzioso.
Struttura delle route
L'App Router organizza le pagine in gruppi:
(marketing)— pagine pubbliche.(auth)— accesso, registrazione, recupero password, conferma email.(authenticated)— l'applicazione vera e propria, dietro autenticazione.api/— endpoint server per ciascun dominio.gmail/eoutlook/— pagine di raccordo per le integrazioni email.
I gruppi di route consentono a ciascuna area di avere il proprio layout e i propri provider. Le pagine marketing, per esempio, non caricano i provider dell'applicazione: il bundle resta piccolo.
Schema del database
Lo schema è multi-tenant, con l'organizzazione come entità radice.
Entità principali — organizzazioni, utenti, clienti, pratiche, contatti, attività.
Entità di supporto — settori, fonti dei lead, dimensioni aziendali, stati delle pratiche, stati delle attività, documenti, metriche.
Ogni tabella di lavoro porta il riferimento all'organizzazione. È il fondamento dell'isolamento descritto in Sicurezza.
Tempo reale
Le modifiche si propagano ai client sottoscritti tramite Supabase Realtime. Il livello di caching davanti alle sottoscrizioni evita di invalidare più del necessario: l'obiettivo è che due persone sulla stessa pratica vedano lo stesso stato senza ricaricare la pagina, e senza generare traffico proporzionale al numero di schede aperte.
Design system
L'interfaccia si appoggia a un sistema di token: colori, tipografia, spaziature, raggi, ombre e animazioni sono definiti centralmente e consumati dai componenti.
I tratti caratteristici: Inter come carattere di interfaccia, molto bianco e grigio chiaro, grigio quasi nero per le azioni primarie, blu come accento per link e stati di focus, raggi ampi sui contenitori in primo piano e ombre molto morbide.
La landing e la documentazione che stai leggendo usano una tipografia diversa dal prodotto, per distinguersi come materiale di comunicazione, ma condividono palette, raggi e rapporti di spaziatura.
Ambienti e rilascio
Il progetto usa una pipeline di integrazione e rilascio continui con controlli di qualità — lint, verifica dei tipi, test, audit di sicurezza — prima di ogni distribuzione. Il ramo di sviluppo pubblica su un ambiente di anteprima; il ramo principale segue una strategia che valida il rilascio prima di applicare modifiche allo schema di produzione.