portfolio — backend integration service
HRMS Attendance Sync API
Biometric devices to database, automated.
A FastAPI service bridging ZKSoftware biometric fingerprint devices to HRMS SQL Server workflows — syncing employee records, importing punch logs, calculating attendance via stored procedures, and streaming live punch events over Socket.IO.
Python
FastAPI
pyzk
SQL Server
Socket.IO
pymssql
JWT Auth
Pydantic
Docker
overview
HR teams relying on ZKSoftware fingerprint devices typically export attendance data manually and import it into their HRMS separately. This service automates that entire pipeline — connecting directly to devices over the network, pulling only new punch records since the last sync, inserting them into SQL Server, and triggering stored-procedure-based attendance calculations. A Socket.IO layer adds live punch monitoring for dashboards that need real-time visibility.
system architecture
Hardware
ZKSoftware Device
Fingerprint scanner — employee records, punch logs, device metadata
→
Service
FastAPI + pyzk
REST endpoints, sync workflows, JWT auth, controller/route separation
→
Persistence
SQL Server
Bulk inserts, stored procedures for attendance calculation and leave rules
→
Realtime
Socket.IO
Live punch-log events emitted to connected dashboard clients
key features
Biometric Device Integration
Communicates with ZKSoftware fingerprint devices via pyzk — fetching device info, storage, employees, and punch logs directly over the network.
Smart Attendance Sync
Imports only new punch records by checking the latest stored timestamp — avoiding duplicate entries on repeated syncs.
Employee CRUD on Device
Add, update, remove, and sync employee records between the biometric device and the HRMS database from a single API surface.
Stored Procedure Orchestration
Triggers SQL Server stored procedures for attendance calculation, flag updates, empty-day handling, and leave verification — keeping HR rules in the database where they belong.
Realtime Punch Streaming
Socket.IO events emit live attendance logs to connected clients. Streaming can be started or stopped via API, with a watch-status endpoint for health checks.
Docker Deployment
Separate Dockerfiles and Compose configs for local development and production — ready to slot into a wider HRMS infrastructure stack.
module structure
| routes/ | FastAPI endpoint definitions for attendance, employees, devices, and authentication |
| controller/ | Business logic for syncing, attendance calculation, realtime monitoring, and device operations |
| models/ | Pydantic request and response schemas |
| utils/ | SQL Server connection management, Socket.IO setup, and ZK device connectivity helpers |
| bg/ | Background worker components for continuous realtime attendance log monitoring |
implementation highlights
01Implemented a timestamp-based incremental sync strategy — each run checks the latest punch record in SQL Server and imports only newer entries from the device, making repeated syncs safe and efficient without a deduplication table.
02Delegated complex attendance rule logic to SQL Server stored procedures — keeping domain-specific HR calculations (leave, empty-day handling, flags) close to the data and leaving the API as a clean orchestration layer.
03Added a Socket.IO event layer on top of the sync pipeline so dashboards receive live punch activity without polling — the streaming worker can be started and stopped at runtime via REST endpoints.
04Separated route definitions from controller logic across all four modules (device, employee, attendance, auth) — keeping the project maintainable as HRMS requirements grow without route handlers becoming business-logic monoliths.
full tech stack
PythonFastAPIPydanticUvicornpyzkSocket.IOSQL ServerpymssqlJWTDockerDocker Compose