How ibrahim-el-sawy/odoo-zkteco-attendance works
1. What this repo is
- This is an Odoo addon for ZKTeco attendance synchronization.
- The architecture centers on an incoming JSON API inside Odoo that receives logs from an upstream Python device-collector service.
2. High-level system boundary
- Outside Odoo: ZKTeco biometric devices and a polling/forwarding Python service.
- Inside Odoo: HTTP controller, normalization/business logic, ORM models, access control, and views.
- The main integration boundary is a custom POST endpoint described in the README as /data/json.
3. Primary data flow
- ZKTeco device generates raw attendance punches.
- The Python service collects logs from one or more devices.
- Each log batch is serialized as JSON and sent to Odoo.
- Odoo receives the payload, interprets the event as check-in/check-out, matches the employee, and creates attendance records.
4. HTTP/API layer
- The controllers/ package is the ingress point.
- controllers/controllers.py is the likely route definition for the JSON endpoint.
- This layer is responsible for request parsing, validation, and handing off payloads to the business logic layer.
5. Payload compatibility and legacy handling
- controllers/zk_old_service.py strongly suggests support for the legacy/older ZKTeco payload format shown in the README.
- controllers/logic_method.py likely contains the transformation logic that converts raw device payloads into Odoo-friendly attendance semantics.
- controllers/zk_config.py likely holds endpoint/device configuration or constants used by the controller and parser.
6. Business logic boundary
- The repo separates transport concerns from attendance rules.
- The logic layer is where the system would:
- normalize timestamps and device metadata,
- determine whether a punch is IN or OUT,
- map device identity fields such as EmpCode or UserID to Odoo employees,
- decide whether to create, update, or skip an attendance record.
7. Odoo data model layer
- models/models.py is the ORM layer for any persistent configuration or sync-related records.
- In an Odoo integration like this, the model layer typically owns mappings, sync state, device configuration, or auxiliary records needed by the controller.
8. Admin/UI layer
- views/views.xml provides the Odoo form/tree/search views needed to configure and monitor the sync module.
- This is the operational surface for administrators, separate from the machine-to-machine API.
9. Security and access control
- security/ir.model.access.csv defines model access permissions.
- That indicates the module is intended to be managed through standard Odoo security rules rather than bypassing the ORM.
10. Demo data
- demo/demo.xml provides sample configuration or records for testing and demonstration.
- This usually supports installation-time validation of the module’s UI and workflow.
11. Technology/runtime implications
- The runtime is Odoo’s Python framework.
- The integration is synchronous HTTP-based, not message-queue-based.
- Persistence and business operations flow through Odoo ORM, not direct database writes.
12. Diagram-ready summary
- A useful architecture diagram would show:
- ZKTeco devices feeding a Python collector service,
- the collector sending JSON to the Odoo controller endpoint,
- the controller invoking parsing/business logic,
- then writing via Odoo models/ORM into the attendance domain,
- with views and security rules as the admin/configuration plane.
Main entry points: models.py Sync models · controllers.py JSON endpoint · logic_method.py Payload parser · demo.xml Demo data
Components 13
Outside Odoo
Upstream devices and forwarding service that produce the attendance payloads.
- ZKTeco devices · Physical devices that generate raw punches and device logs.
- Collector service · Upstream Python service that polls devices and forwards JSON batches.
Inside Odoo
Controller, logic, ORM, and admin surface for the attendance sync addon.
- JSON endpoint · Custom POST ingress point for attendance payloads.
controllers/controllers.py - Payload parser · Transforms incoming device payloads into Odoo-ready attendance semantics.
controllers/logic_method.py - Legacy handler · Supports older ZKTeco payload formats and backward compatibility.
controllers/zk_old_service.py - Config constants · Shared endpoint and device configuration used by the controller layer.
controllers/zk_config.py - Sync models · Persistent records for module state, mappings, or sync-related configuration.
models/models.py - Attendance records · Resulting attendance entries created or updated through the Odoo ORM.
- Employee match · Resolves device identity fields like EmpCode or UserID to Odoo employees.
- In/out rules · Determines whether a punch is interpreted as check-in or check-out.
- Admin views · Form, tree, and search views for configuration and monitoring.
views/views.xml - Access rules · Model access permissions managed through Odoo security rules.
security/ir.model.access.csv - Demo data · Example configuration or records for installation and testing.
demo/demo.xml
Connections 15
- ZKTeco devices → Collector service: raw punches · Devices emit attendance logs that the collector polls and bundles.
- Collector service → JSON endpoint: POST JSON · The collector forwards a batch of logs to the Odoo endpoint.
- JSON endpoint → Config constants: uses config · The controller relies on shared configuration and constants.
- JSON endpoint → Payload parser: dispatches · Incoming payloads are parsed and normalized after request handling.
- JSON endpoint → Legacy handler: legacy path · Older payload formats are routed through compatibility handling.
- Payload parser → Employee match: matches user · Device identity fields are mapped to Odoo employees.
- Payload parser → In/out rules: interprets punch · Raw punches are classified as check-in or check-out.
- In/out rules → Sync models: sync state · Rules drive whether attendance data is created or updated.
- Employee match → Sync models: lookup data · Mappings and sync-related records are stored in Odoo models.
- Sync models → Attendance records: writes ORM · The module persists attendance outcomes through the Odoo ORM.
- Payload parser → Attendance records: creates records · Normalized events are converted into attendance entries.
- Admin views → Sync models: configures · Admins manage sync configuration through Odoo views.
- Access rules → Sync models: permits access · Security rules govern who can manage the module's models.
- Demo data → Admin views: seeds UI · Demo records support installation and workflow validation.
- Demo data → Sync models: sample config · Demo XML provides example module data and settings.