HCM Lite — Enterprise AI-Assisted Human Capital Management

Building a Production-Grade AI Human Capital Management System in 3 Hours at Saylani AI Hackathon

🏗️ Architecture & Tech Stack

Frontend: Next.js 16 (App Router & Turbopack), Tailwind CSS, Lucide Icons, Mobile-First PWA Responsive Layout. Deployed on Vercel.
Backend: FastAPI (Python 3.12), SQLAlchemy 2.0 ORM, Pydantic v2 validation. Deployed on AWS EC2 (Ubuntu Linux) via Docker and reverse SSL tunneling.
Database: PostgreSQL with ACID transactions, automated schema creation, and relationship cascades.
AI & NLP Engine: Azure OpenAI Service (gpt-5.4-mini) with bilingual prompt-tuning (English & Roman Urdu) and tool-calling.
Communications & Storage: Azure Communication Services for automated transactional emails & 4-digit OTPs, and ImgBB Cloud API for organization branding.

The Admin portal delivers centralized governance over the entire enterprise structure and access controls.

First-Run Organization Setup Wizard: Dynamic onboarding to configure office hours, grace periods, half-day thresholds, and GPS office coordinates.
Trusted IP Whitelisting: Strict IP-based access control where administrators can configure allowed IP ranges for Admin, HR, and Employees to eliminate unauthorized remote access.
User Lifecycle & Automated Credentials: Creating a user triggers automated backend email delivery dispatching credentials securely to the employee.
Immutable Audit Trail: Tamper-proof logging recording actor ID, action type, entity, and JSON state diffs for all critical system events.

The HR portal is engineered to automate workforce administration, payroll deductions, and predictive retention insights.

Workforce Approvals Queue: Real-time review, approval, or rejection of pending leaves and attendance correction requests with custom HR commentary.
Automated Payroll & Late Penalties:
- Calculates gross, basic, medical, and house-rent allowances.
- Enforces the hackathon penalty rule: 3 Late arrivals = 0.5 Day salary deduction.
- Dynamic half-day and absence deductions.
- One-click PDF payslip generator streamed directly to the client.
Predictive Workforce Analytics:
- Attrition Risk Scoring: Identifies employees at risk of departure based on market compensation parity, tenure, and absence patterns.
- Absence Anomaly Flags: Spots irregular patterns (e.g., partial shifts or repeated missed punch-outs).

Designed for speed and simplicity, giving employees autonomy over their daily attendance and requests.

Camera Biometrics + Haversine Geofencing:
- Captures browser webcam video feed and verifies real-time face presence.
- Pulls device GPS coordinates and verifies location using the Haversine distance formula against the company geofence perimeter (150m radius).
- Enforces same-day deduplication to prevent double check-ins.
AI Smart Leave Parser (English & Roman Urdu):
- Employees can apply for leave in everyday natural language:
  - English: "I need next Monday and Tuesday off for my sister's wedding"
  - Roman Urdu: "Mujhe agle hafte bukhar ki wajah se 2 din chutti chahiye"
- AI instantly populates the leave type, start date, end date, and reason.
Self-Service Payslips & Attendance Calendar: Direct PDF payslip downloads and historical punch-in logs with self-service correction requests.

Accessible across all dashboards via a persistent floating drawer:

Integrated with role-based tool calling.
HR / Admin queries: "Who is on leave today?", "Who came late most often this month?", "Summarize this month's attendance rate".
Employee queries: "How many casual leaves do I have left?", "What is the office late arrival policy?".
Strictly enforces data boundaries (e.g., politely refusing salary disclosure of colleagues).

Dockerized Architecture: Standardized multi-stage containerization with Docker Compose orchestrating both the FastAPI backend and PostgreSQL database.
Defense in Depth: Zero SQL injection vulnerability (parameterized ORM), cryptographic JWT HS256 signatures, bcrypt hashing, and IDOR protection on all endpoints.
High Availability: Hosted on AWS EC2 with automated systemd process supervision and Cloudflare SSL termination.