Nilai_Clock/CLAUDE.md

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)