Stack Tecnico¶

Panoramica¶

Livello	Tecnologia	Note
Backend	NestJS + TypeScript	Strict mode, nessun `any`
ORM	TypeORM	Schema gestito via entities
Database	PostgreSQL 16	Docker in dev, nativo in prod
Frontend	React 18 + Vite + TypeScript	SPA, build statica servita da Nginx
Styling	TailwindCSS v3.4+	`tailwindcss-animate` obbligatorio
Icone	Lucide React	Unico set icone autorizzato
Routing	React Router DOM v6/v7	Client-side routing
State	React Context	No Redux, no Zustand
HTTP	Axios	Token Bearer iniettato nei default headers
i18n	i18next + react-i18next	UI 100% italiano
Web server	Nginx	Proxy verso Node, serve dist frontend
Process manager	PM2	Gestisce backend e frontend
Automazione	n8n	Server separato (192.168.40.80)

Backend — NestJS¶

Il backend segue l'architettura modulare di NestJS: ogni funzionalità è un modulo autonomo con il proprio controller, service e entity.

Flusso di una Richiesta¶

Browser
  └─→ Nginx (443/9443)
        └─→ NestJS (3001 dev / 3000 prod)
              ├── TenantMiddleware      ← identifica il tenant
              ├── JwtAuthGuard          ← valida token, carica utente dal DB
              ├── RolesGuard            ← verifica il ruolo richiesto
              ├── AuditInterceptor      ← logga automaticamente le azioni
              ├── MaintenanceInterceptor ← blocca se in manutenzione
              └── Controller → Service → TypeORM → PostgreSQL

Configurazione Ambiente¶

Il backend sceglie il file .env in base a NODE_ENV:

development → carica .env
production → carica .env.production

I secrets (JWT, OAuth, password DB, API keys) vivono esclusivamente nei file .env — mai nel codice, mai nel repository.

Frontend — React + Vite¶

SPA (Single Page Application) servita come build statica da Nginx in produzione. In sviluppo gira il dev server Vite con HMR (Hot Module Replacement).

Punti chiave¶

Il token JWT viene salvato in localStorage e iniettato in ogni richiesta Axios via defaults.headers
AuthContext gestisce lo stato globale di autenticazione
ProtectedRoute reindirizza a /login se non autenticato
AxiosInterceptor cattura i 401 e fa logout automatico

Database¶

PostgreSQL 16. L'ORM TypeORM gestisce le migrazioni tramite entities TypeScript. Il flag DB_SYNCHRONIZE=true è attivo solo in dev — in produzione le migrazioni sono manuali.

PM2 — Processi Attivi¶

Nome PM2	Ambiente	Porta	Directory
`dev-backend`	dev	3001	`backend/`
`dev-frontend`	dev	5173	`frontend/`
`prod-backend`	prod	3000	`backend/`

Build sicura

Non usare mai npm run build direttamente — può causare freeze. Usare gli alias npm-build-fe (frontend) e npm-build-be (backend). Prima di avviare qualsiasi servizio: bash scripts/kill_zombie.sh