DuoSync

Il Problema

Tutto è nato dalla difficoltà di trovare un orario per andare in palestra con un mio amico. La situazione era particolare: non era semplice comprendere in maniera chiara quando fossimo liberi, e soprattutto non avevamo quasi mai orari definiti in anticipo. Tra impegni di lavoro, appuntamenti e routine quotidiane che cambiano di giorno in giorno, coordinare gli orari richiedeva continui messaggi che potevano richiedere molti messaggi e molto tempo solo per capire quando entrambi eravamo liberi.

DuoSync nasce da questa esigenza concreta ed è stato progettato per funzionare in situazioni dove gli orari non sono fissi e la comunicazione diretta non è sempre la soluzione più pratica. Supporta fino a 10 utenti, permettendo di visualizzare la disponibilità condivisa e ricevere notifiche quando qualcuno aggiorna i propri impegni.

La Soluzione

DuoSync è un’applicazione web progressiva costruita con Next.js 16 che permette a gruppi fino a 10 utenti di gestire i propri appuntamenti e visualizzare automaticamente i momenti di disponibilità condivisa. L’applicazione offre una timeline visiva che mostra la disponibilità personale e quella condivisa, gestione appuntamenti one-time e ricorrenti, notifiche push per sincronizzazione automatica, supporto multi-lingua (italiano/inglese), tema chiaro/scuro, e architettura feature-based per manutenibilità e scalabilità.

Come Funziona

Il cuore dell’applicazione è la timeline di disponibilità, che mostra due visualizzazioni: la timeline personale mostra tutti gli appuntamenti dell’utente attivo con colori distinti per categoria (sonno, altri impegni, disponibile), mentre la timeline condivisa evidenzia in verde i momenti in cui tutti gli utenti sono liberi contemporaneamente, facilitando la pianificazione di attività comuni.

Gli appuntamenti possono essere creati in due modalità: one-time per impegni specifici di una data, o ricorrenti con giorni della settimana selezionabili. Il sistema valida automaticamente che non ci siano sovrapposizioni e suggerisce il prossimo slot disponibile quando necessario.

Non è necessario inserire appuntamenti tutti i giorni: l’applicazione è pensata per essere utilizzata quando serve, non come un calendario da aggiornare quotidianamente. Quando un utente si ricorda di aggiornare i propri impegni e conferma tramite il pulsante “Conferma”, viene inviata automaticamente una notifica push agli altri utenti (se hanno abilitato le notifiche), avvisandoli che l’utente specifico ha confermato i propri impegni. Questo sistema evita che qualcuno si dimentichi di aggiornare: la notifica serve da promemoria e permette agli altri di vedere immediatamente quando la disponibilità è stata aggiornata.

Le Sfide Tecniche

La gestione degli appuntamenti ricorrenti ha richiesto un’architettura a due livelli: i template ricorrenti sono salvati nella tabella recurring_appointments con i giorni della settimana, mentre quando viene richiesta la lista per una data specifica, il sistema applica i template ricorrenti attivi per quel giorno e li combina con gli appuntamenti one-time. Questo approccio permette di modificare o eliminare i template senza dover aggiornare migliaia di record.

L’implementazione delle notifiche push ha richiesto l’integrazione con Web Push API, gestione delle VAPID keys, registrazione delle subscription nel database, e un service worker per gestire l’arrivo delle notifiche. Ho implementato un sistema che invia notifiche solo quando un utente conferma esplicitamente i propri impegni, evitando spam e mantenendo l’utente informato solo quando necessario.

Architettura e Design Patterns

L’applicazione segue un’architettura feature-based dove ogni dominio (appointments, users, availability) ha la propria cartella con servizi di business logic puri e context per la gestione dello stato. I componenti sono presentazionali e ricevono dati tramite hook custom, mantenendo la separazione tra logica e presentazione.

Il sistema di state management utilizza React Context con provider isolati per feature. Ogni feature espone un context provider e un hook custom (es. useAppointments, useUsers) che i componenti utilizzano per accedere allo stato. Questo pattern evita prop drilling e mantiene lo stato locale alla feature, migliorando le performance con re-render mirati.

La persistenza dei dati è gestita tramite Drizzle ORM con PostgreSQL. Ho implementato un sistema di migrazioni schema-first dove lo schema è definito in TypeScript e sincronizzato con il database tramite Drizzle Kit. Le query sono ottimizzate con indici su userId e date per performance efficienti anche con molti appuntamenti.

L’architettura API segue il pattern Server/Client separation di Next.js: le route API (/app/api/*) gestiscono la validazione e chiamano i servizi di database, mentre i servizi client-side (features/*/services/*.service.ts) utilizzano fetch() per chiamare le API routes. Questo mantiene una chiara separazione tra browser e server, con validazione sia lato client (per UX) che lato server (per sicurezza).

Showcase video

Dettagli Tecnici

1
duosync/
2
├── app/                    # Next.js App Router
3
│   ├── api/                # API routes (server-side)
4
│   │   ├── appointments/   # Endpoints per appuntamenti
5
│   │   ├── notifications/  # Endpoints per push notifications
6
│   │   └── users/          # Endpoints per utenti
7
│   ├── admin/              # Area amministrativa
8
│   ├── onboarding/         # Setup iniziale
9
│   └── page.tsx            # Dashboard principale
10
├── components/             # Componenti UI riutilizzabili
11
│   ├── dashboard/          # Componenti specifici dashboard
12
│   ├── header/              # Header con user switcher
13
│   ├── layout/              # Layout components
14
│   └── ui/                  # Radix UI components
15
├── features/               # Logica di business isolata
16
│   ├── appointments/        # Gestione appuntamenti
17
│   │   ├── services/        # Business logic pura
18
│   │   └── appointments-context.tsx
19
│   ├── availability/        # Calcolo disponibilità
20
│   │   └── services/
21
│   └── users/               # Gestione utenti
22
│       ├── services/
23
│       └── users-context.tsx
24
├── hooks/                  # Custom hooks riutilizzabili
25
│   ├── use-other-user-appointments.ts
26
│   ├── use-time-input-validation.ts
27
│   └── useNotifications.ts
28
├── lib/                    # Utilities e servizi
29
│   ├── db/                  # Database schema e connection
30
│   ├── time/                # Utility per gestione tempo
31
│   └── notifications/       # Servizio push notifications
32
├── types/                   # TypeScript types globali
33
│   └── index.tsx
34
└── i18n/                    # Traduzioni e context i18n
35
    ├── en.json
36
    └── it.json

1
// Success
2
{ appointments: Appointment[] }
3
{ appointmentsByUser: Record<number, Appointment[]> }
4
{ users: UserProfile[] }
5

6
// Error
7
{ error: string }

1
const { t, locale, setLocale } = useI18n()
2
const greeting = t('dashboard.greeting', { name: 'Mario' })