Mocauto APIDocumentazione tecnica

Piattaforma backend NestJS per la gestione di veicoli, scadenze, spese, eventi e notifiche · API REST · Infrastruttura AWS via CDK

Inizia con l'autenticazione

Architettura

Infrastruttura AWS

🔐

Autenticazione robusta

JWT + Refresh Token rotation, sliding window con grace period, social login Google/Apple, reset password, revoca globale delle sessioni.

Vedi flusso

👥

Gestione utenti & RBAC

Ruoli USER / ADMIN / SUPERADMIN, soft delete, password hashing bcrypt + pepper, profilo con immagine S3.

API Utenti

🚗

Veicoli, scadenze e spese

CRUD auto multiutente, scadenze con promemoria e ripetizioni, spese categorizzate con riepiloghi mensili.

API Veicoli

🎉

Eventi & richieste

Pubblicazione eventi dal backoffice, visibilità in app per gli ONLINE, raccolta richieste di partecipazione con notifica email agli admin.

API Eventi

🔔

Notifiche push & in-app

Notifiche persistite con stato is_read, push asincrone via SQS FIFO → Lambda dispatcher APNs / FCM.

API Notifiche

📎

Allegati polimorfici

Sistema attachments su S3 con presigned URL, validazioni server-side, conferma in 2 step, CDN CloudFront.

API Attachments

🏗️

Architettura modulare

DTO client-specific (APP vs BACKOFFICE), guard di ownership, exception filters strutturati, snake_case ↔ camelCase trasparente, sistema email con fallback SMTP.

Architettura

☁️

AWS via CDK

ECS Fargate dietro API Gateway + ALB, RDS PostgreSQL, S3 + CloudFront, SQS+Lambda per email e push, Secrets Manager, CloudWatch.

Overview infra

Quick start

bash

# 1. Clona e installa
git clone <repo>
cd mocauto-api
npm install

# 2. Avvia i servizi di sviluppo
docker compose up -d         # postgres + mailhog

# 3. Prepara il database
npm run prisma:migrate

# 4. Avvia l'app
npm run start:dev            # http://localhost:3000

# 5. Apri questa documentazione
npm run docs:dev             # http://localhost:5173

Mappa rapida

Area	Quando consultarla
Autenticazione	Implementare login mobile/web, refresh, reset password, social login.
Architettura	Aggiungere un nuovo modulo, capire DTO/guard/interceptor/filter.
Filters & DTO	Costruire query lista paginata o gestire le differenze APP vs BACKOFFICE.
Eventi / Notifiche	Funzionalità nuove introdotte dalla v0.0.47.
Infrastruttura	Capire dove vive ciascun servizio AWS e come fare deploy.

Convenzioni di scrittura

snake_case sui body/query/response delle API REST
camelCase all'interno del codice NestJS (Interceptor SnakeToCamelInterceptor gestisce la conversione)
Tutte le date in formato YYYY-MM-DD per i campi Date, ISO 8601 per i DateTime
Risposte di errore con error_code strutturato (vedi Exception Filters)