# ibrahim-el-sawy/odoo-zkteco-attendance architecture

> Architecture diagram of the GitHub repository ibrahim-el-sawy/odoo-zkteco-attendance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibrahim-el-sawy/odoo-zkteco-attendance
- Repository: https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance

## Overview

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/models.py`](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/models/models.py) (Sync models), [`controllers/controllers.py`](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/controllers.py) (JSON endpoint), [`controllers/logic_method.py`](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/logic_method.py) (Payload parser), [`demo/demo.xml`](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/demo/demo.xml) (Demo data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["Outside Odoo"]
  node_zkteco_devices(("ZKTeco devices<br/>biometric source"))
  node_collector_service["Collector service<br/>python forwarder"]
end

subgraph group_odoo["Inside Odoo"]
  node_json_endpoint["JSON endpoint<br/>http controller<br/>[controllers.py]"]
  node_payload_parser["Payload parser<br/>normalization logic<br/>[logic_method.py]"]
  node_legacy_handler["Legacy handler<br/>compat parser<br/>[zk_old_service.py]"]
  node_zk_config["Config constants<br/>controller config<br/>[zk_config.py]"]
  node_attendance_models[("Sync models<br/>orm models<br/>[models.py]")]
  node_attendance_domain[("Attendance records<br/>hr attendance domain")]
  node_employee_mapping["Employee match<br/>identity mapping"]
  node_checkin_checkout["In/out rules<br/>attendance rules"]
  node_views_ui["Admin views<br/>odoo views<br/>[views.xml]"]
  node_access_rules["Access rules<br/>security ACL"]
  node_demo_data["Demo data<br/>sample records<br/>[demo.xml]"]
end

node_zkteco_devices -->|"raw punches"| node_collector_service
node_collector_service -->|"POST JSON"| node_json_endpoint
node_json_endpoint -.->|"uses config"| node_zk_config
node_json_endpoint -->|"dispatches"| node_payload_parser
node_json_endpoint -.->|"legacy path"| node_legacy_handler
node_payload_parser -->|"matches user"| node_employee_mapping
node_payload_parser -->|"interprets punch"| node_checkin_checkout
node_checkin_checkout -->|"sync state"| node_attendance_models
node_employee_mapping -->|"lookup data"| node_attendance_models
node_attendance_models -->|"writes ORM"| node_attendance_domain
node_payload_parser -->|"creates records"| node_attendance_domain
node_views_ui -->|"configures"| node_attendance_models
node_access_rules -->|"permits access"| node_attendance_models
node_demo_data -.->|"seeds UI"| node_views_ui
node_demo_data -.->|"sample config"| node_attendance_models

click node_json_endpoint "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/controllers.py"
click node_payload_parser "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/logic_method.py"
click node_legacy_handler "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/zk_old_service.py"
click node_zk_config "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/zk_config.py"
click node_attendance_models "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/models/models.py"
click node_views_ui "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/views/views.xml"
click node_access_rules "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/security/ir.model.access.csv"
click node_demo_data "https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/demo/demo.xml"

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_zkteco_devices,node_collector_service toneBlue
class node_json_endpoint,node_payload_parser,node_legacy_handler,node_zk_config,node_attendance_models,node_attendance_domain,node_employee_mapping,node_checkin_checkout,node_views_ui,node_access_rules,node_demo_data toneAmber
```

## Components

### Outside Odoo

Upstream devices and forwarding service that produce the attendance payloads.

- **ZKTeco devices**: biometric source · Physical devices that generate raw punches and device logs.
- **Collector service**: python forwarder · 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](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/controllers.py): http controller · Custom POST ingress point for attendance payloads. · `controllers/controllers.py`
- [Payload parser](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/logic_method.py): normalization logic · Transforms incoming device payloads into Odoo-ready attendance semantics. · `controllers/logic_method.py`
- [Legacy handler](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/zk_old_service.py): compat parser · Supports older ZKTeco payload formats and backward compatibility. · `controllers/zk_old_service.py`
- [Config constants](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/controllers/zk_config.py): controller config · Shared endpoint and device configuration used by the controller layer. · `controllers/zk_config.py`
- [Sync models](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/models/models.py): orm models · Persistent records for module state, mappings, or sync-related configuration. · `models/models.py`
- **Attendance records**: hr attendance domain · Resulting attendance entries created or updated through the Odoo ORM.
- **Employee match**: identity mapping · Resolves device identity fields like EmpCode or UserID to Odoo employees.
- **In/out rules**: attendance rules · Determines whether a punch is interpreted as check-in or check-out.
- [Admin views](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/views/views.xml): odoo views · Form, tree, and search views for configuration and monitoring. · `views/views.xml`
- [Access rules](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/security/ir.model.access.csv): security ACL · Model access permissions managed through Odoo security rules. · `security/ir.model.access.csv`
- [Demo data](https://github.com/ibrahim-el-sawy/odoo-zkteco-attendance/blob/main/demo/demo.xml): sample records · Example configuration or records for installation and testing. · `demo/demo.xml`

## Connections

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