# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

NiLai-Clock is a worker attendance management system with role-based dashboards for workers and managers. It's built as a Vue.js SPA with an Express.js backend, featuring QR code attendance tracking, geofencing, and comprehensive reporting capabilities.

## Commands

### Development
- `npm run dev` - Start frontend development server (Vite on port 5173)
- `npm run backend` - Start backend server (Express on port 3000)  
- `npm run dev:all` - Run both frontend and backend concurrently
- `npm install` - Install dependencies

### Production
- `npm run build` - Build for production using Vite
- `npm run preview` - Preview production build locally

### Code Quality
- `npm run lint` - Run ESLint with auto-fix
- `npm run format` - Format code using Prettier

## Architecture

### Frontend (Vue.js)
- **Framework**: Vue 3 with Composition API
- **Build Tool**: Vite with Vue plugin and TailwindCSS
- **Routing**: Vue Router with hash-based routing and role-based guards
- **State**: Session storage for authentication (userId, userRole, token)
- **Styling**: TailwindCSS v4 with responsive design
- **Internationalization**: Vue I18n with English (en) and Malay (ms) locales

### Backend (Express.js)
- **Server**: Express with CORS, supports both HTTP and HTTPS
- **Database**: MySQL with connection pooling (mysql2)
- **Authentication**: JWT tokens with bcrypt for password hashing
- **Routes**: Separated into manager (`/api/managers/*`) and worker (`/api/*`) routes

### Key Components Structure

#### Views (Role-Based)
- **Worker**: `WorkerDashboard`, `WorkerHistory`, `WorkerSettings`, `WorkerChangePassword`  
- **Manager**: `ManagerDashboard`, `ManagerAttendanceRecord`
- **Auth**: `Login` (supports both roles)

#### Components  
- **Management**: `PersonnelManagement`, `GeofenceManagement`, `QrCodeManagement`, `KillSwitchManagement`
- **UI**: `Toast` notifications with `useToast` composable
- **Reporting**: `WarningReporting` with CSV export capabilities

### Authentication Flow
- Role-based routing with `meta: { requiresAuth: true, role: 'worker|manager' }`
- Navigation guards redirect users to appropriate dashboards
- Session storage manages authentication state
- API requests include JWT tokens via Authorization header

### Key Libraries
- **Maps**: Leaflet with drawing capabilities for geofencing
- **QR Codes**: html5-qrcode for scanning, qrcode for generation
- **Geospatial**: @turf/turf for geographical calculations
- **Data Export**: json2csv for attendance reports
- **UUID**: For device identification and worker login tracking

## Environment Configuration

Create `.env` file with:
```
DB_HOST=your_database_host
DB_USER=your_database_user  
DB_PASSWORD=your_database_password
DB_NAME=your_database_name
DB_PORT=your_database_port
VITE_API_BASE_URL=your_api_base_url
```

Optional SSL configuration:
- `SSL_ENABLED=true`
- `HTTP_PORT=3000` 
- `HTTPS_PORT=3443`

## Development Notes

- Frontend uses hash-based routing for better deployment compatibility
- Backend supports both HTTP and HTTPS with configurable ports
- CORS configured for multiple origins including mobile app protocols
- Database connection is tested on server startup with proper error handling
- All API calls go through centralized `apiFetch` utility with error handling
- ESLint configured to ignore unused variables/parameters prefixed with underscore
- Prettier integrated with Vue ESLint config for consistent formatting

## Database Schema

The application manages worker attendance with these core entities:
- **Workers**: Authentication, device UUID tracking, role assignment
- **Managers**: Administrative access and permissions
- **Attendance Records**: Clock in/out with location and timestamp data  
- **Geofences**: Location boundaries for valid attendance tracking
- **QR Codes**: Dynamic codes for attendance verification

## Docker Support

Includes Docker configuration:
- `Dockerfile` - Node.js Alpine-based container
- `docker-compose.yml` - Multi-service setup with nginx reverse proxy
- Production deployment on port 18080 (nginx) and 18081 (app)