How khaledbinamir/biometric_integration works
1. What this repo is
- This is a Frappe/ERPNext app that sits inside the ERPNext runtime and extends HR attendance with biometric device integration.
- The architectural center is not a separate service: device traffic is handled inside the Frappe web process.
2. Ingress boundary
- Biometric devices call the app over HTTP using two protocols: ZKTeco ADMS push and EBKN FkWeb push.
- Requests to /iclock/* and /ebkn are intercepted by Frappe’s page renderer / WSGI-level routing, so devices never hit normal page lookup.
- This means the integration boundary is the web request layer, not a queue worker or external middleware.
3. Protocol adapter layer
- biometric_integration/adapters/ contains a small brand-specific adapter abstraction.
- base.py defines the common contract, while zkteco.py and ebkn.py implement device-specific parsing, response formatting, and command/push semantics.
- This layer isolates protocol differences from the rest of the system.
4. Core business services
- services/checkin.py turns incoming punch data into ERPNext Employee Checkin records.
- services/user_sync.py manages enrollment/template propagation and employee-to-device identity mapping.
- services/command_processor.py handles the command queue lifecycle: enqueue, dispatch on poll, and mark success/failure.
- These services form the main application logic and are the boundary between raw device traffic and ERPNext data.
5. Persistence model / doctypes
- The app stores its state in Frappe doctypes under biometric_integration/biometric_integration/doctype/.
- Key entities are:
- Attendance Device: one physical device, including last contact and sync state.
- Attendance Device User: maps device PINs/templates to ERPNext employees.
- Attendance Device Link: which devices a user is enrolled on.
- Attendance Device Command: pending actions to send back to devices.
- Attendance Device Log: audit trail of all traffic and errors.
- Attendance Integration Settings: singleton configuration.
- This is the system’s durable state and should be drawn as the central data store in the architecture.
6. Main data flows
- Attendance flow: device pushes punch data → adapter parses it → checkin service creates ERPNext attendance data.
- Enrollment flow: device sends enrollment/template data → user-sync service creates/updates Attendance Device User → template is stored and linked to the employee.
- Reverse command flow: employee status or profile changes in ERPNext → command service enqueues actions → device later polls and receives them.
- The key architectural pattern is push in, queued push back out.
7. ERPNext integration points
- The app depends on ERPNext HR concepts, especially Employee and Employee Checkin.
- The README notes a standard attendance_device_id field used to auto-match device PINs to employees.
- There are also client-side customizations in public/js/employee.js and doctype scripts to support the Desk UI.
8. Configuration and environment control
- attendance_integration_settings is the operator control plane for enabling listener behavior, configuring endpoints, logging, and device discovery.
- The proxy/ package (configurator.py, detector.py, template.py) generates and manages Nginx listener configuration for self-hosted deployments or produces a ready-to-paste block for constrained environments.
- This is important because devices speak plain HTTP while ERPNext deployments may be HTTPS-only.
9. Operational support and caching
- utils/device_cache.py and utils/installation.py support runtime lookups and environment setup.
- The README notes Redis usage for EBKN multi-block buffering, so the architecture includes a small cache/buffer layer in addition to database persistence.
- Attendance Device Log provides optional audit logging and also captures unknown-device discovery without breaking device connectivity.
10. Migration and extension surface
- patches/v2_0/ contains upgrade logic, including settings-doctype renaming and migration from v1.
- fixtures/ adds custom fields and property setters into ERPNext, showing that the app extends the host schema rather than owning the whole data model.
- api.py, cli.py, and commands/ are the external control surface for administrative actions and scripted operations, while hooks.py wires the app into Frappe’s lifecycle.
11. How to draw the architecture
- Show four major zones: biometric devices, Frappe ingress/routing, service layer + doctypes, and ERPNext HR records.
- Add a side path for Nginx/proxy configuration management and a support path for logging/cache/migrations.
- The most important directional arrows are: device push into Frappe, service writes into doctypes/ERPNext, and queued commands polling back out to devices.
Main entry points: user_sync.py User sync · ebkn.py EBKN adapter · checkin.py Checkin service · zkteco.py ZKTeco adapter
Components 21
Biometric devices
External attendance terminals pushing punch, enrollment, and command-poll traffic.
- Devices · ZKTeco ADMS and EBKN FkWeb terminals that push attendance and enrollment data, then poll for commands.
Frappe ingress
WSGI/page routing and protocol adapters inside the ERPNext web process.
- Ingress routing · WSGI/page-rendering boundary that intercepts /iclock/* and /ebkn requests before normal page lookup.
biometric_integration/renderers.py - Adapter base · Common adapter interface for parsing requests, formatting responses, and normalizing device semantics.
biometric_integration/adapters/base.py - ZKTeco adapter · Implements ZKTeco push and command-poll behavior.
biometric_integration/adapters/zkteco.py - EBKN adapter · Implements EBKN push, buffering, and response semantics.
biometric_integration/adapters/ebkn.py
Service layer
Business logic that converts device traffic into ERPNext and device-state operations.
- Checkin service · Transforms device punch data into Employee Checkin records.
biometric_integration/services/checkin.py - User sync · Manages enrollment templates, identity mapping, and employee-to-device linkage.
biometric_integration/services/user_sync.py - Command processor · Enqueues device actions, dispatches them on poll, and records success or failure.
biometric_integration/services/command_processor.py
Doctypes
Durable application state stored in Frappe doctypes.
- Device · Physical device record with contact status and sync state.
biometric_integration/biometric_integration/doctype/attendance_device/attendance_device.json - Device user · Maps device PINs and templates to ERPNext employees.
biometric_integration/biometric_integration/doctype/attendance_device_user/attendance_device_user.json - Device link · Tracks which devices each user is enrolled on.
biometric_integration/biometric_integration/doctype/attendance_device_link/attendance_device_link.json - Device command · Pending actions waiting to be delivered back to devices.
biometric_integration/biometric_integration/doctype/attendance_device_command/attendance_device_command.json - Device log · Audit trail for traffic, errors, and unknown-device discovery.
biometric_integration/biometric_integration/doctype/attendance_device_log/attendance_device_log.json - Settings · Operator control plane for listener behavior, discovery, logging, and endpoint setup.
biometric_integration/biometric_integration/doctype/attendance_integration_settings/attendance_integration_settings.json
ERPNext HR
Host ERPNext records and custom HR extensions.
- Employee · Host employee master record used for device identity matching.
- Checkin · Standard ERPNext attendance record created from device punches.
Ops support
Configuration, caching, migrations, and administrative control surfaces.
- Desk UI · Client-side customizations for employee forms and related doctype behavior.
biometric_integration/public/js/employee.js - Proxy config · Generates and manages listener configuration for HTTP device access behind ERPNext deployments.
biometric_integration/proxy/configurator.py - Device cache · Redis-backed buffering and lookup support, including EBKN multi-block buffering.
biometric_integration/utils/device_cache.py - Migrations · Versioned upgrade logic for settings renames and v1-to-v2 migration.
biometric_integration/patches/v2_0/migrate_from_v1.py - API surface · External control surface for scripted actions, hooks, and lifecycle wiring.
biometric_integration/api.py
Connections 27
- Devices → Ingress routing: HTTP push/poll · Devices send punch, enrollment, and command-poll requests into the Frappe web process.
- Ingress routing → Adapter base: dispatches to · Ingress selects the correct protocol adapter for each request.
- Adapter base → ZKTeco adapter: implements · ZKTeco protocol specialization.
- Adapter base → EBKN adapter: implements · EBKN protocol specialization.
- ZKTeco adapter → Checkin service: punches · Parsed punch data becomes attendance checkins.
- EBKN adapter → Checkin service: punches · EBKN punch payloads feed attendance creation.
- ZKTeco adapter → User sync: enrollment · Device enrollment and template data are normalized for identity sync.
- EBKN adapter → User sync: enrollment · EBKN enrollment payloads update employee-device mappings.
- ZKTeco adapter → Command processor: polls commands · Device requests queued actions when it polls.
- EBKN adapter → Command processor: polls commands · Device requests queued actions when it polls.
- Checkin service → Checkin: writes · Creates ERPNext Employee Checkin records.
- User sync → Device user: updates · Creates or updates the device-user identity mapping.
- User sync → Device link: links · Stores which devices each employee is enrolled on.
- Command processor → Device command: queues · Stores pending commands for later device delivery.
- Checkin service → Device: updates state · Tracks last contact and sync-related device status.
- User sync → Device: updates state · Maintains enrollment and synchronization state per device.
- Command processor → Device: updates state · Records command lifecycle and device sync state.
- Ingress routing → Device log: logs traffic · Requests, errors, and unknown-device events are recorded for auditability.
- Checkin service → Employee: matches employee · Attendance data is associated to the ERPNext employee master using device IDs.
- User sync → Employee: binds employee · Enrollment and identity mapping reference ERPNext employees.
- Proxy config → Settings: reads config · Listener generation is driven by operator settings.
- Settings → Ingress routing: enables listener · Controls whether the device listener is active and how it behaves.
- Device cache → EBKN adapter: buffers blocks · Supports EBKN multi-block buffering and runtime lookups.
- Migrations → Settings: renames/reshapes · Upgrade patches migrate settings and older schema versions.
- API surface → Proxy config: admin control · Administrative and scripted operations can trigger configuration and lifecycle actions.
- API surface → Migrations: lifecycle · Hooks and commands participate in setup and upgrade flows.
- Desk UI → Employee: customizes UI · Desk-side behavior supports employee-related custom fields and workflows.