aitrainee-1/ukt_hr_portal

Purpose and Entry Points

UKTextiles HR System is an on-premise HR/ERP platform for factory operations. A Django REST backend serves the React HR portal and separate employee mobile/web clients. Primary entry points are Django routing and startup in backend/config/urls.py, backend/api/urls.py, and backend/manage.py; the HR SPA starts at frontend/src/main.tsx and routes from frontend/src/App.tsx.

Runtime and Deployment Boundary

The backend is Django 5/DRF on Python 3.11+ with PostgreSQL; the frontend is React 19/Vite on Node 20+. Production is intended for a Windows on-premise machine using Waitress, Nginx, NSSM, and Cloudflare Tunnel. The backend remains on the factory LAN to reach eSSL/ZKTeco biometric devices over TCP 4370; Cloudflare exposes HTTPS API access to employee clients. Deployment guidance: docs/DEPLOYMENT_GUIDE.md, backend/config/settings.py.

API, Identity, and Authorization

All clients use the /api surface. JWT authentication distinguishes HR users and employees, while HR portal roles use hierarchical module permissions and request middleware. Department managers are employees with scoped approval authority for teams. Core boundaries are implemented in backend/api/auth.py, backend/api/permission_registry.py, and backend/api/permission_middleware.py; the frontend applies matching navigation/view locks through frontend/src/contexts/AuthContext.tsx, frontend/src/components/HrLayout.tsx, and frontend/src/lib/permission-modules.ts.

Domain Persistence and Organization

A central Django model layer holds organization, employee, attendance, leave, payroll, recruitment, documents, sessions, chat, and backup data. PostgreSQL is the system of record; migrations establish the evolving schema. API serializers and feature-specific view modules expose this model rather than a separate service layer. Key paths: backend/api/models.py, backend/api/serializers.py, backend/api/migrations/0001_initial.py.

Attendance Acquisition and Decision Engine

Raw punches arrive from biometric sync, manual imports, geo punches/on-duty, and missing-punch corrections. The canonical engine converts those inputs into per-employee/day records, which payroll and reporting consume. Staff strict/simple rules, shifts, lateness, permissions, night relaxation, and production segments are distinct policy branches. The defining boundary is raw logs versus final AttendanceDayRecord verdicts: backend/api/biometric_sync.py, backend/api/attendance_final.py, backend/api/shift_engine.py.

Scheduling, Devices, and Operations

Django startup initializes APScheduler jobs for fixed biometric syncs, configurable auto-sync rules, and scheduled backups. Biometric pulls use pyzk; backups can target local storage and Google Drive. Manual operational entry points also exist as management commands. Relevant paths: backend/api/apps.py, backend/api/auto_sync.py, backend/api/backup_scheduler.py, backend/api/google_drive.py, backend/api/management/commands/sync_biometric.py.

HR Workflow Modules

Feature-specific API views own lifecycle actions: leave approvals update attendance; manager approvals delegate scoped decisions; payroll calculates staff/production earnings and deductions from final attendance; salary/document modules generate PDFs; recruitment includes spaCy-backed resume scoring. Principal modules: backend/api/leave_views.py, backend/api/manager_views.py, backend/api/payroll_views.py, backend/api/salary_slip_views.py, backend/api/resume_screening_ml.py.

HR Portal Client Architecture

The Vite SPA is a role-aware administrative client. Pages map to HR modules, shared layouts enforce portal context, and generated Orval hooks plus custom hooks call Django APIs. TanStack Query supports cached/polled server state and long-running pipeline contexts display job progress. Key paths: frontend/src/pages/hr/Dashboard.tsx, frontend/src/lib/api-client/index.ts, frontend/src/lib/api-client/custom-hooks.ts, frontend/src/contexts/PayrollGenerationContext.tsx, frontend/src/components/BiometricSyncPipeline.tsx.