PlayPadel

Il problema

Il club gestiva prenotazioni su Playtomic, comunicazioni su WhatsApp e organizzazione partite con fogli di calcolo e memoria. Lo staff passava ore a riconciliare disponibilità campi, rincorrere i no-show e notificare manualmente i giocatori sui cambi orario.

Vincoli

• L'API Playtomic è la source of truth per le prenotazioni: il sistema deve sincronizzare, non sostituire.
• I giocatori si aspettano messaggi WhatsApp, non email, e la consegna deve essere affidabile e tracciabile.
• Budget single VPS: niente Kubernetes, niente queue service gestito, niente complessità operativa superflua.
• Dati reali di giocatori in produzione: conformità GDPR e scrubbing PII non negoziabili.

Cosa abbiamo costruito

Piattaforma operativa full-stack: pannello admin per lo staff, sync automatica Playtomic, pipeline notifiche WhatsApp, gestione partite e reporting, deployata come container Docker su VPS singola con rollback automatico.

Architettura

Architettura esagonale (ports and adapters) che isola la logica di dominio dalle preoccupazioni infrastrutturali.

• Domain layer: regole prenotazione, lifecycle partite, policy notifiche. TypeScript puro, zero import da framework.
• Application layer: use case orchestrano i servizi di dominio attraverso port definiti.
• Infrastructure adapter: client REST Playtomic, sender WhatsApp Twilio, repository Prisma, error reporting Sentry.
• Presentation layer: admin UI Next.js con server component e API route tipizzate.

Integrazione Playtomic

Job di sync schedulati recuperano disponibilità campi e prenotazioni dall'API Playtomic. I conflitti vengono rilevati a livello di dominio e mostrati allo staff prima che diventino doppie prenotazioni. L'adapter gestisce rate limit, paginazione e drift di versione API dietro un'interfaccia port stabile.

Outbox WhatsApp / Twilio

I messaggi outbound passano da un outbox transazionale: l'evento di dominio viene persistito prima, poi un worker in background consegna via API WhatsApp Twilio. Invii falliti ritentano con backoff esponenziale; i fallimenti permanenti vengono loggati e mostrati nel pannello admin. Nessun messaggio perso perché la chiamata HTTP è fallita.

Data layer

PostgreSQL con ORM Prisma. Le migration sono versionate e applicate in CI prima del deploy. I cambi schema seguono il pattern expand-contract per evitare downtime sul database single-instance.

Infrastruttura e rollback

Docker Compose su VPS singola. GitHub Actions builda e pusha immagini su GHCR; lo script di deploy fa pull, esegue health check e rollback automatico all'immagine precedente se il nuovo container non parte. Tempo di rollback osservato: sotto i 60 secondi.

Osservabilità

Sentry per error tracking con scrubbing PII configurato a livello SDK: nomi, numeri di telefono e corpi messaggio vengono rimossi prima che gli eventi lascino il server. Logging strutturato per failure delle integrazioni; nessun dato personale nelle righe di log.

Risultati

• Tempo staff su riconciliazione manuale prenotazioni ridotto da ore al giorno a minuti a settimana.
• Tasso consegna WhatsApp sopra il 99% con audit trail completo via tabella outbox.
• Zero downtime non pianificato da deploy falliti da quando è attivo il rollback automatico.
• La piattaforma gestisce il picco di prenotazioni del weekend senza intervento manuale.

Stack

TypeScript · Node.js · Next.js · PostgreSQL · Prisma · Docker · GitHub Actions · Twilio · Sentry · Cloudflare