# frappe/biometric-attendance-sync-tool architecture

> Architecture diagram of the GitHub repository frappe/biometric-attendance-sync-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frappe/biometric-attendance-sync-tool
- Repository: https://github.com/frappe/biometric-attendance-sync-tool

## Overview

This tool polls biometric attendance devices and sends attendance records to ERPNext. Users can configure and run it through a GUI, the CLI loop, or a Windows service. The main sync routine schedules polling, retries saved dumps, filters records using prior successes and an import start date, then pushes punches; it also supports Shift Type synchronization. The excerpts show the core calls, but do not expose every device-processing detail, so unverified integrations are omitted.

Main entry points: [`erpnext_sync.py`](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py) (Sync scheduler), [`gui.py`](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/gui.py) (Configuration GUI), [`erpnext_sync_win.py`](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync_win.py) (Windows service wrapper), [`local_config.py.template`](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/local_config.py.template) (Runtime configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user_entry["User entry points"]
  node_gui["Configuration GUI<br/>[gui.py]"]
  node_cli_loop["CLI sync loop<br/>[erpnext_sync.py]"]
  node_win_wrapper["Windows service wrapper"]
  node_win_base["Windows service base<br/>[SMWinservice.py]"]
end

subgraph group_sync_runtime["Sync runtime"]
  node_config["Runtime configuration"]
  node_scheduler["Sync scheduler<br/>[erpnext_sync.py]"]
  node_device_pull["Device attendance pull<br/>[erpnext_sync.py]"]
  node_attendance_process["Punch filtering and mapping<br/>[erpnext_sync.py]"]
  node_attendance_push["ERPNext attendance push<br/>[erpnext_sync.py]"]
  node_shift_sync["Shift Type sync<br/>[erpnext_sync.py]"]
end

subgraph group_state_logs["State and logs"]
  node_status_store[("Sync status store<br/>[erpnext_sync.py]")]
  node_attendance_logs["Attendance and activity logs<br/>[erpnext_sync.py]"]
end

subgraph group_integrations["External systems"]
  node_bas["Biometric attendance device"]
  node_erpnext["ERPNext instance"]
end

node_operator(("Operator"))

node_operator -->|"configures and starts"| node_gui
node_operator -->|"runs sync"| node_cli_loop
node_operator -->|"installs service"| node_win_wrapper
node_gui -->|"writes configuration"| node_config
node_gui -->|"starts subprocess"| node_cli_loop
node_win_wrapper -->|"inherits service framework"| node_win_base
node_win_wrapper -->|"calls main"| node_scheduler
node_cli_loop -->|"calls main"| node_scheduler
node_scheduler -->|"reads settings"| node_config
node_scheduler -->|"reads and updates"| node_status_store
node_scheduler -->|"processes configured devices"| node_device_pull
node_scheduler -->|"updates shift timestamps"| node_shift_sync
node_scheduler -->|"reads retry dumps"| node_attendance_logs
node_device_pull -->|"fetches attendance"| node_bas
node_device_pull -->|"passes attendance records"| node_attendance_process
node_attendance_process -->|"reads last success"| node_attendance_logs
node_attendance_process -->|"submits mapped punches"| node_attendance_push
node_attendance_push -->|"posts attendance"| node_erpnext
node_shift_sync -->|"updates shift records"| node_erpnext

click node_gui "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/gui.py"
click node_cli_loop "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_win_wrapper "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync_win.py"
click node_win_base "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/SMWinservice.py"
click node_config "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/local_config.py.template"
click node_scheduler "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_device_pull "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_attendance_process "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_attendance_push "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_shift_sync "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_status_store "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py"
click node_attendance_logs "https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.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_gui,node_cli_loop,node_win_wrapper,node_win_base toneBlue
class node_config,node_scheduler,node_device_pull,node_attendance_process,node_attendance_push,node_shift_sync toneAmber
class node_status_store,node_attendance_logs toneMint
class node_bas,node_erpnext toneRose
class node_operator toneIndigo
```

## Components

### User entry points

- [Configuration GUI](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/gui.py): `gui.py`
- [CLI sync loop](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [Windows service wrapper](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync_win.py): `erpnext_sync_win.py`
- [Windows service base](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/SMWinservice.py): `SMWinservice.py`

### Sync runtime

- [Runtime configuration](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/local_config.py.template): `local_config.py.template`
- [Sync scheduler](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [Device attendance pull](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [Punch filtering and mapping](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [ERPNext attendance push](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [Shift Type sync](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`

### State and logs

- [Sync status store](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`
- [Attendance and activity logs](https://github.com/frappe/biometric-attendance-sync-tool/blob/master/erpnext_sync.py): `erpnext_sync.py`

### External systems

- **Biometric attendance device**
- **ERPNext instance**

### Other components

- **Operator**

## Connections

- Operator → Configuration GUI: configures and starts (evidence: `README.md`)
- Operator → CLI sync loop: runs sync (evidence: `README.md`)
- Operator → Windows service wrapper: installs service (evidence: `README.md`)
- Configuration GUI → Runtime configuration: writes configuration (evidence: `gui.py`)
- Configuration GUI → CLI sync loop: starts subprocess (evidence: `gui.py`)
- Windows service wrapper → Windows service base: inherits service framework (evidence: `erpnext_sync_win.py`)
- Windows service wrapper → Sync scheduler: calls main (evidence: `erpnext_sync_win.py`)
- CLI sync loop → Sync scheduler: calls main (evidence: `erpnext_sync.py`)
- Sync scheduler → Runtime configuration: reads settings (evidence: `erpnext_sync.py`)
- Sync scheduler → Sync status store: reads and updates (evidence: `erpnext_sync.py`)
- Sync scheduler → Device attendance pull: processes configured devices (evidence: `erpnext_sync.py`)
- Sync scheduler → Shift Type sync: updates shift timestamps (evidence: `erpnext_sync.py`)
- Sync scheduler → Attendance and activity logs: reads retry dumps (evidence: `erpnext_sync.py`)
- Device attendance pull → Biometric attendance device: fetches attendance (evidence: `erpnext_sync.py`)
- Device attendance pull → Punch filtering and mapping: passes attendance records (evidence: `erpnext_sync.py`)
- Punch filtering and mapping → Attendance and activity logs: reads last success (evidence: `erpnext_sync.py`)
- Punch filtering and mapping → ERPNext attendance push: submits mapped punches (evidence: `erpnext_sync.py`)
- ERPNext attendance push → ERPNext instance: posts attendance (evidence: `erpnext_sync.py`)
- Shift Type sync → ERPNext instance: updates shift records (evidence: `erpnext_sync.py`)