ZKTeco .NET Middleware Integration

Understood — here’s the cleaned-up **freelancer project delivery for BiometricBridge** without emojis.

---

# Freelancer Project Proposal – **BiometricBridge**

### A Middleware for ZKTeco Biometric Devices (Push & Pull Communication)

---

## Project Overview

**BiometricBridge** is a .NET 6+ middleware designed to connect **ZKTeco biometric devices** (fingerprint, face, card readers) with a **MySQL database** and optionally forward logs to an **external HRMS/Payroll API**.

It replaces ZKTeco’s proprietary `iclock.dll` by mimicking the `/iclock/*` endpoints in ASP.NET Core, giving you full control over devices, users, logs, and commands.

---

## Objectives

1. Implement push communication from devices → server.

* Endpoints: `/iclock/cdata`, `/iclock/devicecmd` (acknowledgement).
2. Implement pull communication from server → devices.

* Devices poll `/iclock/getrequest` for queued commands.
* Server responds with commands like `REBOOT`, `DATA QUERY`, `DELETE USER`.
3. Provide admin APIs to manage:

* Users (add, list, delete).
* Devices (activity, info).
* Biometric templates (finger, face, bio).
* Attendance logs.
4. Synchronize attendance logs with an external HRMS API (e.g., Swipebox).
5. Provide secure, token-based authentication for admin endpoints.

---

## Tech Stack

* Backend: ASP.NET Core Web API (.NET 6+)
* Database: MySQL 8
* ORM: EF Core (or Dapper for optimized queries)
* Auth: Token authentication via DB table `authentication`
* Logging: File + Database logging
* External Integration: REST API client for HRMS (e.g., Swipebox)
* Deployment: IIS or Docker

---

## Solution Architecture

```
ZKTeco Devices <── Push/Pull ──> BiometricBridge API <──> MySQL Database
│
└──> External HRMS API
```

* Push (Device → API): Attendance logs, user info, templates.
* Pull (API → Device): Commands (Reboot, Download, Delete).
* DB: Central repository for logs, users, biometrics, commands, device activity.
* External API: Forward attendance to HR/payroll systems.

---

## Project Structure

```
BiometricBridge.sln

/src
├── BiometricBridge.Api/ # Web API layer
│ ├── Controllers/
│ │ ├── HomeController.cs
│ │ ├── DeviceController.cs # Push endpoints
│ │ ├── CommandController.cs # Pull/command endpoints
│ │ ├── UserController.cs # Manage users
│ │ └── HealthController.cs # check/checkdb
│ ├── DTOs/
│ │ ├── AttRecordDto.cs
│ │ ├── UserDto.cs
│ │ ├── BioTemplateDto.cs
│ │ └── DeviceDto.cs
│ ├── Middleware/
│ │ ├── AuthMiddleware.cs
│ │ └── ErrorHandlingMiddleware.cs
│ ├── Program.cs
│ └── Startup.cs

├── BiometricBridge.Core/ # Business/domain logic
│ ├── Entities/ # Maps DB models
│ │ ├── AttRecord.cs
│ │ ├── UserInfo.cs
│ │ ├── BioTemplate.cs
│ │ ├── DeviceActivity.cs
│ │ ├── DeviceCommand.cs
│ │ └── DeviceParameters.cs
│ ├── Interfaces/
│ │ ├── IAttendanceService.cs
│ │ ├── IUserService.cs
│ │ ├── IBioTemplateService.cs
│ │ ├── IDeviceService.cs
│ │ └── ICommandService.cs
│ ├── Services/
│ │ ├── AttendanceService.cs
│ │ ├── UserService.cs
│ │ ├── BioTemplateService.cs
│ │ ├── DeviceService.cs
│ │ └── CommandService.cs
│ └── Helpers/
│ ├── LicenseValidator.cs
│ ├── LogHelper.cs
│ └── TimezoneHelper.cs

├── BiometricBridge.Infrastructure/ # Persistence + external APIs
│ ├── Data/
│ │ ├── ApplicationDbContext.cs
│ │ └── Migrations/
│ ├── Repositories/
│ │ ├── AttendanceRepository.cs
│ │ ├── UserRepository.cs
│ │ ├── BioTemplateRepository.cs
│ │ ├── DeviceRepository.cs
│ │ └── CommandRepository.cs
│ ├── External/
│ │ └── SwipeboxApiClient.cs
│ ├── Logging/
│ │ └── FileLogger.cs
│ └── Config/
│ └── appsettings.json

└── BiometricBridge.Shared/ # Shared utilities
├── Models/
│ ├── ErrorViewModel.cs
│ └── ApiResponse.cs
└── Constants/
├── Routes.cs
└── Messages.cs

/tests
├── BiometricBridge.Tests/
│ ├── Controllers/
│ ├── Services/
│ ├── Repositories/
│ └── Middleware/
```

---

## Deliverables

* ASP.NET Core Web API with `/iclock/*` endpoints.
* MySQL database schema + migrations.
* Push/pull communication tested with real devices.
* CRUD APIs for Users, Devices, Templates, Commands.
* Log sync with external HRMS.
* Unit & integration test coverage.
* Setup guide & API documentation (Swagger + Postman collection).

---

## Timeline & Milestones

1. Week 1


---

## Freelancer Handover

* Source code (`BiometricBridge.sln`).
* Database schema & migrations.
* Documentation (setup, API usage).
* Postman collection for APIs.
* Dockerfile (optional, for container deployment).

---

Do you want me to now prepare a **ready-to-use MySQL schema (tables and relationships)** that goes with this project plan?