# khaledbinamir/biometric_integration architecture

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

- Interactive diagram: https://gitdiagram.com/khaledbinamir/biometric_integration
- Repository: https://github.com/khaledbinamir/biometric_integration

## Overview

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: [`biometric_integration/services/user_sync.py`](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/user_sync.py) (User sync), [`biometric_integration/adapters/ebkn.py`](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/ebkn.py) (EBKN adapter), [`biometric_integration/services/checkin.py`](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/checkin.py) (Checkin service), [`biometric_integration/adapters/zkteco.py`](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/zkteco.py) (ZKTeco adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_devices["Biometric devices"]
  node_device_terminals["Devices<br/>hardware endpoints"]
end

subgraph group_frappe["Frappe ingress"]
  node_renderers["Ingress routing<br/>Frappe routing<br/>[renderers.py]"]
  node_adapter_base["Adapter base<br/>protocol contract<br/>[base.py]"]
  node_adapter_zkteco["ZKTeco adapter<br/>ADMS adapter<br/>[zkteco.py]"]
  node_adapter_ebkn["EBKN adapter<br/>FkWeb adapter<br/>[ebkn.py]"]
end

subgraph group_core["Service layer"]
  node_checkin_service["Checkin service<br/>attendance ingest<br/>[checkin.py]"]
  node_user_sync_service["User sync<br/>enrollment sync<br/>[user_sync.py]"]
  node_command_service["Command processor<br/>command queue"]
end

subgraph group_data["Doctypes"]
  node_attendance_device[("Device<br/>doctypes state")]
  node_device_user[("Device user<br/>doctypes state")]
  node_device_link[("Device link<br/>doctypes state")]
  node_device_command["Device command<br/>doctypes queue"]
  node_device_log["Device log<br/>audit log"]
  node_integration_settings["Settings<br/>singleton config"]
end

subgraph group_erpnext["ERPNext HR"]
  node_employee["Employee<br/>ERPNext HR"]
  node_employee_checkin["Checkin<br/>ERPNext HR"]
end

subgraph group_ops["Ops support"]
  node_employee_js["Desk UI<br/>client customization<br/>[employee.js]"]
  node_proxy_tools["Proxy config<br/>nginx helper<br/>[configurator.py]"]
  node_device_cache{{"Device cache<br/>runtime cache<br/>[device_cache.py]"}}
  node_migrations["Migrations<br/>upgrade patches<br/>[migrate_from_v1.py]"]
  node_api_cli_hooks["API surface<br/>admin entrypoints<br/>[api.py]"]
end

node_device_terminals -->|"HTTP push/poll"| node_renderers
node_renderers -->|"dispatches to"| node_adapter_base
node_adapter_base -->|"implements"| node_adapter_zkteco
node_adapter_base -->|"implements"| node_adapter_ebkn
node_adapter_zkteco -->|"punches"| node_checkin_service
node_adapter_ebkn -->|"punches"| node_checkin_service
node_adapter_zkteco -->|"enrollment"| node_user_sync_service
node_adapter_ebkn -->|"enrollment"| node_user_sync_service
node_adapter_zkteco -->|"polls commands"| node_command_service
node_adapter_ebkn -->|"polls commands"| node_command_service
node_checkin_service -->|"writes"| node_employee_checkin
node_user_sync_service -->|"updates"| node_device_user
node_user_sync_service -->|"links"| node_device_link
node_command_service -->|"queues"| node_device_command
node_checkin_service -->|"updates state"| node_attendance_device
node_user_sync_service -->|"updates state"| node_attendance_device
node_command_service -->|"updates state"| node_attendance_device
node_renderers -->|"logs traffic"| node_device_log
node_checkin_service -->|"matches employee"| node_employee
node_user_sync_service -->|"binds employee"| node_employee
node_proxy_tools -->|"reads config"| node_integration_settings
node_integration_settings -.->|"enables listener"| node_renderers
node_device_cache -.->|"buffers blocks"| node_adapter_ebkn
node_migrations -->|"renames/reshapes"| node_integration_settings
node_api_cli_hooks -.->|"admin control"| node_proxy_tools
node_api_cli_hooks -.->|"lifecycle"| node_migrations
node_employee_js -.->|"customizes UI"| node_employee

click node_renderers "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/renderers.py"
click node_adapter_base "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/base.py"
click node_adapter_zkteco "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/zkteco.py"
click node_adapter_ebkn "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/ebkn.py"
click node_checkin_service "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/checkin.py"
click node_user_sync_service "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/user_sync.py"
click node_command_service "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/command_processor.py"
click node_attendance_device "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device/attendance_device.json"
click node_device_user "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_user/attendance_device_user.json"
click node_device_link "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_link/attendance_device_link.json"
click node_device_command "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_command/attendance_device_command.json"
click node_device_log "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_log/attendance_device_log.json"
click node_integration_settings "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_integration_settings/attendance_integration_settings.json"
click node_employee_js "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/public/js/employee.js"
click node_proxy_tools "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/proxy/configurator.py"
click node_device_cache "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/utils/device_cache.py"
click node_migrations "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/patches/v2_0/migrate_from_v1.py"
click node_api_cli_hooks "https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/api.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_device_terminals toneBlue
class node_renderers,node_adapter_base,node_adapter_zkteco,node_adapter_ebkn toneAmber
class node_checkin_service,node_user_sync_service,node_command_service toneMint
class node_attendance_device,node_device_user,node_device_link,node_device_command,node_device_log,node_integration_settings toneRose
class node_employee,node_employee_checkin toneIndigo
class node_employee_js,node_proxy_tools,node_device_cache,node_migrations,node_api_cli_hooks toneTeal
```

## Components

### Biometric devices

External attendance terminals pushing punch, enrollment, and command-poll traffic.

- **Devices**: hardware endpoints · 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](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/renderers.py): Frappe routing · WSGI/page-rendering boundary that intercepts /iclock/* and /ebkn requests before normal page lookup. · `biometric_integration/renderers.py`
- [Adapter base](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/base.py): protocol contract · Common adapter interface for parsing requests, formatting responses, and normalizing device semantics. · `biometric_integration/adapters/base.py`
- [ZKTeco adapter](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/zkteco.py): ADMS adapter · Implements ZKTeco push and command-poll behavior. · `biometric_integration/adapters/zkteco.py`
- [EBKN adapter](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/adapters/ebkn.py): FkWeb 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](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/checkin.py): attendance ingest · Transforms device punch data into Employee Checkin records. · `biometric_integration/services/checkin.py`
- [User sync](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/user_sync.py): enrollment sync · Manages enrollment templates, identity mapping, and employee-to-device linkage. · `biometric_integration/services/user_sync.py`
- [Command processor](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/services/command_processor.py): command queue · 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](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device/attendance_device.json): doctypes state · Physical device record with contact status and sync state. · `biometric_integration/biometric_integration/doctype/attendance_device/attendance_device.json`
- [Device user](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_user/attendance_device_user.json): doctypes state · Maps device PINs and templates to ERPNext employees. · `biometric_integration/biometric_integration/doctype/attendance_device_user/attendance_device_user.json`
- [Device link](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_link/attendance_device_link.json): doctypes state · Tracks which devices each user is enrolled on. · `biometric_integration/biometric_integration/doctype/attendance_device_link/attendance_device_link.json`
- [Device command](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_command/attendance_device_command.json): doctypes queue · Pending actions waiting to be delivered back to devices. · `biometric_integration/biometric_integration/doctype/attendance_device_command/attendance_device_command.json`
- [Device log](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_device_log/attendance_device_log.json): audit log · Audit trail for traffic, errors, and unknown-device discovery. · `biometric_integration/biometric_integration/doctype/attendance_device_log/attendance_device_log.json`
- [Settings](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/biometric_integration/doctype/attendance_integration_settings/attendance_integration_settings.json): singleton config · 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**: ERPNext HR · Host employee master record used for device identity matching.
- **Checkin**: ERPNext HR · Standard ERPNext attendance record created from device punches.

### Ops support

Configuration, caching, migrations, and administrative control surfaces.

- [Desk UI](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/public/js/employee.js): client customization · Client-side customizations for employee forms and related doctype behavior. · `biometric_integration/public/js/employee.js`
- [Proxy config](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/proxy/configurator.py): nginx helper · Generates and manages listener configuration for HTTP device access behind ERPNext deployments. · `biometric_integration/proxy/configurator.py`
- [Device cache](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/utils/device_cache.py): runtime cache · Redis-backed buffering and lookup support, including EBKN multi-block buffering. · `biometric_integration/utils/device_cache.py`
- [Migrations](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/patches/v2_0/migrate_from_v1.py): upgrade patches · Versioned upgrade logic for settings renames and v1-to-v2 migration. · `biometric_integration/patches/v2_0/migrate_from_v1.py`
- [API surface](https://github.com/khaledbinamir/biometric_integration/blob/develop/biometric_integration/api.py): admin entrypoints · External control surface for scripted actions, hooks, and lifecycle wiring. · `biometric_integration/api.py`

## Connections

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