# VigilanzaTurni - Sistema Gestione Turni per Istituti di Vigilanza

## Overview
VigilanzaTurni is a professional 24/7 shift management system designed for security companies. It offers multi-role authentication (Admin, Coordinator, Guard, Client), comprehensive guard and site management, 24/7 shift planning, a live operational dashboard with KPIs, reporting for worked hours, and a notification system. The system supports multi-location operations (Roccapiemonte, Milano, Roma) managing 250+ security personnel across different branches. The project aims to streamline operations and enhance efficiency for security institutes.

## User Preferences
- Interfaccia in italiano
- Dark mode di default
- Design operativo e funzionale (non decorativo)
- Focus su efficienza e densità informativa
- **Testing**: Tutti i test vengono eseguiti ESCLUSIVAMENTE sul server esterno (vt.alfacom.it) con autenticazione locale (non Replit Auth)

## System Architecture

### Stack Tecnologico
- **Frontend**: React + TypeScript + Tailwind CSS + Shadcn UI
- **Backend**: Express.js + TypeScript
- **Database**: PostgreSQL (Neon) with Drizzle ORM
- **Autenticazione**: Replit Auth (OIDC)
- **State Management**: TanStack Query v5
- **Routing**: Wouter

### Design System
- **Font Principale**: Inter (sans-serif)
- **Font Monospace**: JetBrains Mono
- **Colori**: Primary Blue, Status Green, Orange, Red, Gray for various operational states.
- **Tema**: Dark mode by default, with light mode support.
- **Componenti**: Shadcn UI with an operational design.

### Database Schema
The database includes core tables for `users`, `guards`, `certifications`, `sites`, `shifts`, `shift_assignments`, and `notifications`. Advanced scheduling and constraints are managed via `guard_constraints`, `site_preferences`, `contract_parameters`, `training_courses`, `holidays`, `holiday_assignments`, `absences`, and `absence_affected_shifts`. All tables include appropriate foreign keys and unique constraints to maintain data integrity.

### API Endpoints
Comprehensive RESTful API endpoints are provided for Authentication, Users, Guards, Sites, Shifts, and Notifications, supporting full CRUD operations with role-based access control.

### Frontend Routes
Key frontend routes include `/`, `/guards`, `/sites`, `/shifts`, `/reports`, `/notifications`, and `/users`, with access controlled by user roles.

### User Roles
- **Admin**: Full access to all functionalities, managing guards, sites, shifts, and reports.
- **Coordinator**: Shift planning, guard assignment, operational site management, and reporting.
- **Guard**: View assigned shifts, future time-punching, notifications, and personal profile.
- **Client**: View assigned sites, service reporting, and KPIs.

### Key Features
- **Dashboard Operativa**: Live KPIs (active shifts, total guards, active sites, expiring certifications) and real-time shift status.
- **Gestione Guardie**: Complete profiles with skill matrix (armed, fire safety, first aid, driver's license), certification management with automatic expiry, and unique badge numbers.
- **Gestione Siti/Commesse**: Service types (fixed post, patrol, night inspection, quick response) and minimum requirements (guard count, armed, driver's license).
- **Pianificazione Turni**: 24/7 calendar, manual guard assignment, basic constraints, and shift statuses (planned, active, completed, cancelled).
- **Reportistica**: Total hours worked, monthly hours per guard, shift statistics, and data export capabilities.
- **Advanced Planning**: Management of guard constraints (preferences, max hours, rest days), site preferences (preferred/blacklisted guards), contract parameters, training courses, holidays, and absences with substitution system.

## External Dependencies
- **Replit Auth**: For OpenID Connect (OIDC) based authentication.
- **Neon**: Managed PostgreSQL database service.
- **Tailwind CSS**: For utility-first CSS styling.
- **Shadcn UI**: For UI components.
- **Zod**: For schema validation.
- **TanStack Query**: For data fetching and state management.
- **Wouter**: For client-side routing.
- **date-fns**: For date manipulation and formatting.
- **PM2**: Production process manager for Node.js applications.
- **Nginx**: As a reverse proxy for the production environment.
- **Let's Encrypt**: For SSL/TLS certificates.
- **GitLab CI/CD**: For continuous integration and deployment.