# aitrainee-1/ukt_hr_portal architecture

> Architecture diagram of the GitHub repository aitrainee-1/ukt_hr_portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aitrainee-1/ukt_hr_portal
- Repository: https://github.com/aitrainee-1/ukt_hr_portal

## Overview

#### 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`.

Main entry points: [`backend/api/attendance_final.py`](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/attendance_final.py) (Final attendance engine), [`backend/api/biometric_sync.py`](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/biometric_sync.py) (Biometric sync), [`backend/api/models.py`](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/models.py) (Domain model layer), [`frontend/src/App.tsx`](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/App.tsx) (HR pages and layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_hr_spa["HR portal SPA<br/>React/Vite client<br/>[main.tsx]"]
  node_hr_routes["HR pages and layout<br/>portal routing<br/>[App.tsx]"]
  node_client_authz["Client access controls<br/>[AuthContext.tsx]"]
  node_api_client["API hooks and cache<br/>Orval/TanStack client<br/>[index.ts]"]
  node_sync_progress_ui["Sync pipeline UI<br/>React workflow UI"]
  node_employee_clients["Employee clients<br/>mobile/web clients"]
end

subgraph group_backend["Django backend"]
  node_django_entry["Django API routing<br/>Django/DRF entrypoint<br/>[urls.py]"]
  node_identity_authz["JWT identity and permissions<br/>auth middleware<br/>[auth.py]"]
  node_feature_views["HR workflow APIs<br/>DRF feature views<br/>[payroll_views.py]"]
  node_domain_models["Domain model layer<br/>Django ORM models<br/>[models.py]"]
  node_attendance_engine["Final attendance engine<br/>attendance decision engine"]
  node_shift_policy["Shift and policy rules<br/>attendance policy engine<br/>[shift_engine.py]"]
end

subgraph group_operations["Factory operations"]
  node_scheduler["Startup schedulers<br/>APScheduler initialization<br/>[apps.py]"]
  node_biometric_sync["Biometric sync<br/>pyzk acquisition<br/>[biometric_sync.py]"]
  node_backup_jobs["Scheduled backups<br/>backup scheduler"]
  node_biometric_devices{{"eSSL/ZKTeco devices<br/>factory LAN devices"}}
end

subgraph group_data["Data and external services"]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_cloudflare{{"Cloudflare Tunnel<br/>HTTPS exposure"}}
  node_google_drive["Google Drive<br/>backup target<br/>[google_drive.py]"]
end

node_hr_spa -->|"renders"| node_hr_routes
node_hr_routes -->|"applies portal guards"| node_client_authz
node_hr_routes -->|"loads server state"| node_api_client
node_sync_progress_ui -->|"tracks sync jobs"| node_api_client
node_api_client -->|"/api"| node_django_entry
node_employee_clients -->|"HTTPS"| node_cloudflare
node_cloudflare -->|"proxies API"| node_django_entry
node_django_entry -->|"authenticates and authorizes"| node_identity_authz
node_identity_authz -->|"permits requests"| node_feature_views
node_feature_views -->|"reads and updates"| node_domain_models
node_domain_models -->|"persists"| node_postgres
node_feature_views -->|"leave and payroll workflows"| node_attendance_engine
node_attendance_engine -->|"evaluates policies"| node_shift_policy
node_attendance_engine -->|"writes final day records"| node_domain_models
node_scheduler -->|"schedules"| node_biometric_sync
node_scheduler -->|"schedules"| node_backup_jobs
node_biometric_devices -->|"raw punches over LAN"| node_biometric_sync
node_biometric_sync -->|"submits raw logs"| node_attendance_engine
node_biometric_sync -->|"stores raw logs"| node_domain_models
node_backup_jobs -.->|"backs up"| node_postgres
node_backup_jobs -->|"uploads backups"| node_google_drive

click node_hr_spa "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/main.tsx"
click node_hr_routes "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/App.tsx"
click node_client_authz "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_api_client "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/lib/api-client/index.ts"
click node_sync_progress_ui "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/components/BiometricSyncPipeline.tsx"
click node_django_entry "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/config/urls.py"
click node_identity_authz "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/auth.py"
click node_feature_views "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/payroll_views.py"
click node_domain_models "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/models.py"
click node_attendance_engine "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/attendance_final.py"
click node_shift_policy "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/shift_engine.py"
click node_scheduler "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/apps.py"
click node_biometric_sync "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/biometric_sync.py"
click node_backup_jobs "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/backup_scheduler.py"
click node_google_drive "https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/google_drive.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hr_spa,node_hr_routes,node_client_authz,node_api_client,node_sync_progress_ui,node_employee_clients toneBlue
class node_django_entry,node_identity_authz,node_feature_views,node_domain_models,node_attendance_engine,node_shift_policy toneAmber
class node_scheduler,node_biometric_sync,node_backup_jobs,node_biometric_devices toneMint
class node_postgres,node_cloudflare,node_google_drive toneRose
```

## Components

### Clients

- [HR portal SPA](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/main.tsx): React/Vite client · Role-aware administrative portal. · `frontend/src/main.tsx`
- [HR pages and layout](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/App.tsx): portal routing · `frontend/src/App.tsx`
- [Client access controls](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/contexts/AuthContext.tsx): React context and UI guards · `frontend/src/contexts/AuthContext.tsx`
- [API hooks and cache](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/lib/api-client/index.ts): Orval/TanStack client · Generated and custom hooks provide cached and polled API state. · `frontend/src/lib/api-client/index.ts`
- [Sync pipeline UI](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/frontend/src/components/BiometricSyncPipeline.tsx): React workflow UI · `frontend/src/components/BiometricSyncPipeline.tsx`
- **Employee clients**: mobile/web clients · Employee-facing consumers of the HTTPS API.

### Django backend

- [Django API routing](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/config/urls.py): Django/DRF entrypoint · `backend/config/urls.py`
- [JWT identity and permissions](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/auth.py): auth middleware · Separates HR and employee identities with hierarchical module permissions. · `backend/api/auth.py`
- [HR workflow APIs](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/payroll_views.py): DRF feature views · Leave, manager, payroll, salary, and recruitment lifecycle actions. · `backend/api/payroll_views.py`
- [Domain model layer](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/models.py): Django ORM models · Organization, employee, attendance, leave, payroll, documents, and operational data. · `backend/api/models.py`
- [Final attendance engine](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/attendance_final.py): attendance decision engine · Produces canonical per-employee/day attendance verdicts. · `backend/api/attendance_final.py`
- [Shift and policy rules](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/shift_engine.py): attendance policy engine · `backend/api/shift_engine.py`

### Factory operations

- [Startup schedulers](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/apps.py): APScheduler initialization · Starts biometric sync and backup schedules. · `backend/api/apps.py`
- [Biometric sync](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/biometric_sync.py): pyzk acquisition · Pulls raw punches from factory devices; also callable manually. · `backend/api/biometric_sync.py`
- [Scheduled backups](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/backup_scheduler.py): backup scheduler · `backend/api/backup_scheduler.py`
- **eSSL/ZKTeco devices**: factory LAN devices · TCP 4370 punch sources.

### Data and external services

- **PostgreSQL**: system of record
- **Cloudflare Tunnel**: HTTPS exposure · Exposes the on-premise API to employee clients.
- [Google Drive](https://github.com/aitrainee-1/ukt_hr_portal/blob/main/backend/api/google_drive.py): backup target · `backend/api/google_drive.py`

## Connections

- HR portal SPA → HR pages and layout: renders
- HR pages and layout → Client access controls: applies portal guards
- HR pages and layout → API hooks and cache: loads server state
- Sync pipeline UI → API hooks and cache: tracks sync jobs
- API hooks and cache → Django API routing: /api
- Employee clients → Cloudflare Tunnel: HTTPS
- Cloudflare Tunnel → Django API routing: proxies API
- Django API routing → JWT identity and permissions: authenticates and authorizes
- JWT identity and permissions → HR workflow APIs: permits requests
- HR workflow APIs → Domain model layer: reads and updates
- Domain model layer → PostgreSQL: persists
- HR workflow APIs → Final attendance engine: leave and payroll workflows
- Final attendance engine → Shift and policy rules: evaluates policies
- Final attendance engine → Domain model layer: writes final day records
- Startup schedulers → Biometric sync: schedules
- Startup schedulers → Scheduled backups: schedules
- eSSL/ZKTeco devices → Biometric sync: raw punches over LAN
- Biometric sync → Final attendance engine: submits raw logs
- Biometric sync → Domain model layer: stores raw logs
- Scheduled backups → PostgreSQL: backs up
- Scheduled backups → Google Drive: uploads backups