abe4041cd1
Initial commit adds core UI components, including layout elements, form controls, and navigation elements, along with the main application structure and routing. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 99f0fce6-9386-489a-9632-1d81223cab44 Replit-Commit-Checkpoint-Type: full_checkpoint Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/6d543d2c-20b9-4ea6-93fe-70fe9b1d9f80/99f0fce6-9386-489a-9632-1d81223cab44/nGJAldO
140 lines
6.3 KiB
Markdown
140 lines
6.3 KiB
Markdown
# 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 |