# VigilanzaTurni - Security Shift Management System

## Overview

VigilanzaTurni is a professional 24/7 shift management system designed specifically for security and surveillance institutes. The application manages guards, sites, shifts, certifications, and provides comprehensive operational control for security operations.

**Core Purpose:** Streamline security personnel scheduling, credential management, site assignments, and real-time operational oversight with compliance-focused audit trails and reporting.

**Technology Stack:**
- Frontend: React with TypeScript, Vite bundler
- UI Framework: Radix UI components with shadcn/ui (New York style)
- Styling: Tailwind CSS with custom design system
- Backend: Express.js with TypeScript
- Database: PostgreSQL via Neon serverless
- ORM: Drizzle ORM
- Authentication: Replit Auth with OpenID Connect
- State Management: TanStack Query (React Query)
- Form Handling: React Hook Form with Zod validation

## User Preferences

Preferred communication style: Simple, everyday language.

## System Architecture

### Frontend Architecture

**Component Structure:**
- Page-based routing using Wouter for client-side navigation
- Component library built on Radix UI primitives with shadcn/ui styling
- Custom operational components (KPICard, StatusBadge) for security-specific UI
- Responsive sidebar layout (SidebarProvider) with collapsible navigation
- Theme system supporting dark/light modes with operational color palette

**State Management:**
- TanStack Query for server state and API caching
- Custom hooks pattern (useAuth, useIsMobile, useToast) for reusable logic
- Form state managed via React Hook Form with Zod schema validation
- Client-side authentication state derived from user query

**Design System:**
- Material Design principles adapted for operational clarity
- Dark mode as primary interface (operational background: HSL 220 15% 12%)
- Status-based color coding: Green (active), Red (emergency), Orange (alerts), Amber (pending)
- Typography: Inter for UI, JetBrains Mono for technical data (IDs, timestamps)
- Border radius: 9px (lg), 6px (md), 3px (sm) for consistent visual hierarchy

### Backend Architecture

**API Layer:**
- RESTful Express.js server with TypeScript
- Session-based authentication using connect-pg-simple
- Route handlers in `/server/routes.ts` with middleware authentication
- Request/response logging middleware for audit trails
- Error handling middleware with standardized error responses

**Database Design:**
- PostgreSQL schema defined in `/shared/schema.ts` using Drizzle ORM
- Key entities: Users, Guards, Sites, Shifts, ShiftAssignments, Certifications, Notifications
- Enums for role management, shift types, certification status
- Foreign key relationships: Guards → Users, ShiftAssignments → Guards/Shifts, Certifications → Guards
- Automatic timestamp tracking (createdAt, updatedAt)

**Data Access Pattern:**
- Storage abstraction layer in `/server/storage.ts` implementing IStorage interface
- Centralized database operations preventing direct DB access in routes
- Drizzle ORM for type-safe queries with PostgreSQL dialect
- Relationship loading via Drizzle relations for nested data (guards with certifications)

### Authentication & Authorization

**Replit Auth Integration:**
- OpenID Connect flow via `openid-client` library
- Session management with PostgreSQL-backed session store
- User profile synchronization on login (upsertUser pattern)
- Role-based access control via userRoleEnum (admin, coordinator, guard, client)
- Middleware authentication check (`isAuthenticated`) protecting all `/api/*` routes

**Session Security:**
- HTTPOnly cookies with secure flag
- 7-day session TTL with automatic cleanup
- Session data stored in dedicated `sessions` table
- CSRF protection via same-origin policy

### External Dependencies

**Third-party Services:**
- Neon Database: Serverless PostgreSQL with WebSocket connections
- Replit Auth: OAuth/OIDC authentication provider
- Google Fonts: Inter and JetBrains Mono font families

**Key Libraries:**
- `@neondatabase/serverless`: PostgreSQL driver with WebSocket support
- `drizzle-orm`: Type-safe ORM with schema validation
- `drizzle-zod`: Schema-to-Zod validator generation
- `express-session`: Session middleware
- `connect-pg-simple`: PostgreSQL session store
- `passport` + `openid-client`: Authentication strategy
- `@tanstack/react-query`: Async state management
- `react-hook-form` + `@hookform/resolvers`: Form validation
- `date-fns`: Date manipulation and formatting (Italian locale support)
- `wouter`: Lightweight client-side routing
- `class-variance-authority` + `clsx` + `tailwind-merge`: Dynamic styling utilities

**Build & Development:**
- Vite for frontend bundling with React plugin
- esbuild for server-side bundling
- TypeScript with strict mode and path aliases (@/, @shared/, @assets/)
- PostCSS with Tailwind CSS and Autoprefixer

### Data Models

**Core Entities:**
1. **Guards**: Badge number, contact info, skills (armed, fire safety, first aid, driver license, languages), user relationship
2. **Certifications**: Type, issue/expiry dates, status (valid/expiring_soon/expired), attached to guards
3. **Sites**: Name, address, shift type requirements, minimum guards, armed/driver requirements, active status
4. **Shifts**: Time range, site assignment, status (planned/active/completed/cancelled), guard assignments
5. **ShiftAssignments**: Many-to-many relationship between shifts and guards
6. **Notifications**: Type-based alerts (shift_assigned, certification_expiring, shift_reminder), read status

**Business Logic:**
- Certification status auto-update based on expiry date (< 30 days = expiring_soon, past = expired)
- Real-time shift status tracking (active shifts query endpoint)
- Guard-site compatibility checking (armed requirement, skills matching)
- Operational KPIs: active shifts, total guards, active sites, expiring certifications

### Deployment Configuration

**Environment Variables Required:**
- `DATABASE_URL`: PostgreSQL connection string (Neon)
- `SESSION_SECRET`: Session encryption key
- `REPL_ID`: Replit deployment identifier
- `ISSUER_URL`: OIDC provider URL (default: https://replit.com/oidc)
- `REPLIT_DOMAINS`: Allowed authentication domains

**Build Process:**
- Client: `vite build` → `dist/public`
- Server: `esbuild` bundling → `dist/index.js`
- Database migrations: `drizzle-kit push` for schema sync
- Production: Node.js serves static files + API routes