zk_aio_ERP

ZKTeco Attendance System

A full attendance management solution for ZKTeco biometric devices. It includes a real-time logger that streams punch events to a local SQLite database, a feature-rich web dashboard (ERP Console) for attendance management and IT operations, bulk sync utilities, and multi-channel notifications.

Components

File Purpose
main.py Real-time attendance logger — streams live punch events from all devices to the local database and external API
server.py Flask web dashboard (v2.2) — full ERP Console backend with attendance, device management, ticketing, messaging, and admin APIs
sync_all.py Bulk sync CLI — pull all logs from devices and push to API (supports date range and per-device filtering)
sync_db.py Database sync CLI — imports employees from MDB/CSV, pulls device logs into local SQLite
boot_sync_60d.py Startup sync — syncs the last 60 days of logs on system boot
gaes-py-zk/boot_sync_30d.py GAS-edition startup sync — syncs the last 30 days on boot
mdb_tools.py MDB/Access tools — export employees, generate absent reports from MDB backup
telegram_notifier.py Telegram bot — sends device status, punch, and daily report notifications; interactive command handler for attendance queries, employee lookup, device control, and system stats
code.gs Google Apps Script backend — IT Helpdesk, token queues, Drive storage, and GAS-side authentication

Features

Core Attendance

Web Dashboard

Human Resources & Attendance

Reporting & Exports

Hardware Management (ZKTeco Devices)

Notifications

Telegram Bot Commands

The bot responds to the following text commands (or /slash equivalents):

Category Command Description
Attendance today summary Present / absent / total counts + punch count
  today absent Full absent list grouped by department
  dept summary Per-department attendance breakdown
  week summary Day-by-day present/absent from Mon to today
  month summary Department attendance % for the current month
  cache refresh Trigger an immediate data refresh
Employees user attendance Date-wise punches with inline calendar picker
  user search Search by name or badge; shows today’s punch times
  user <name/badge> Direct lookup, e.g. user 1024
  user report Punch times for a specific employee today
  late today Employees who arrived after their shift start
  early exits Employees who left before their shift end
  who is in Employees currently in the office
  top absent Top 10 most absent employees this month
Devices device status Online / offline status of all devices
  device sync Sync time and users across all devices
  device reboot Reboot a device (interactive list)
  unknown users Badge IDs not matched to any employee
  punch feed 20 most recent punch records
System pending punches Punch corrections awaiting approval
  holiday check Today’s holiday and upcoming holidays (30 days)
  db stats Employee count, total records, and DB file size
  help Show the full command reference

IT Services & Collaboration

🆘 SOS Emergency Broadcast

Database & Admin Tools

Built-in IT Toolkit (client-side, no server needed)

Progressive Web App (PWA)

Requirements

Quick Start

Linux

bash install.sh       # installs packages, exports employees, syncs devices
bash attendance.sh    # interactive menu

macOS

brew install mdbtools   # for MDB file reading (optional)
bash install.sh         # installs remaining packages
bash attendance.sh      # interactive menu

Android (Termux)

pkg install python sqlite mdbtools   # system packages
bash install.sh                      # installs Python packages
bash attendance.sh                   # interactive menu

Auto-start on Android boot (Termux:Boot):

  1. Install the Termux:Boot add-on.
  2. Open Termux:Boot once to grant permissions.
  3. Create the boot script: 
    mkdir -p ~/.termux/boot
# Replace ~/ZKTeco with the actual path to your ZKTeco folder
echo '#!/data/data/com.termux/files/usr/bin/bash
cd ~/ZKTeco
python server.py &' > ~/.termux/boot/start-attendance.sh
chmod +x ~/.termux/boot/start-attendance.sh

Windows

attendance.bat        # interactive menu

Manual

python3 -m venv venv
source venv/bin/activate        # Linux/macOS/Termux
# venv\Scripts\activate         # Windows

pip install -r requirements.txt

# Real-time logger (pushes live events to API + local DB)
python main.py

# Web dashboard
python server.py      # open http://localhost:5000

Platform Notes

Feature Windows Linux macOS Android (Termux)
Dashboard (server.py) ✅ ✅ ✅ ✅
Device sync (sync_db.py) ✅ ✅ ✅ ✅
MDB import ✅ pyodbc ✅ mdbtools ✅ mdbtools ✅ mdbtools
Real-time logger (main.py) ✅ ✅ ✅ ✅
Auto-start Task Scheduler / bat systemd launchd Termux:Boot

Configuration

config.json — Real-time logger & boot sync

{
  "name": "Your-System-Name",
  "log_level": "INFO",
  "endpoint": "https://your-domain.example.com/erp-api/sync/empAttSync.php",
  "buffer_limit": 10,
  "devices": [
    { "device_id": 1, "ip_address": "10.20.141.21", "port": 4370 },
    { "device_id": 2, "ip_address": "10.20.141.22", "port": 4370 }
  ],
  "telegram": {
    "bot_token": "YOUR_TELEGRAM_BOT_TOKEN",
    "chat_id": "YOUR_TELEGRAM_CHAT_ID",
    "enabled": false,
    "notifications": {
      "startup": true,
      "end_of_day": true,
      "data_push": true,
      "errors": true,
      "device_status": true
    }
  }
}

settings.ini — Web dashboard

Edit settings.ini to configure device IPs, departments, session timeouts, Telegram settings, and the dashboard port. Key sections:

Section Key settings
[devices] IP list, port, connection timeout, pull timeout
[server] Dashboard port, cache refresh interval
[database] Optional path to MDB backup file
[departments] Excluded depts, collapsed depts, display order
[sessions] Session lifetime, admin/employee inactivity timeout
[app] Version string, default admin password
[telegram] Bot token, chat ID, per-notification toggles, daily report time
[voip] Optional TURN server URL, username, and credential for WebRTC audio through NAT

Utilities

# Sync all logs for a date range
python sync_all.py --from 2026-01-01 --to 2026-04-01

# Sync a specific device only
python sync_all.py --device-id 2

# Import employees + pull device logs into local DB
python sync_db.py

# Export employee list from MDB
python mdb_tools.py export

# Generate today's absent report
python mdb_tools.py today

Docker

docker build -t zkteco-attendance .
docker run --network host zkteco-attendance

License

This project is licensed under the MIT License.

🏢 ERP Console (Web Dashboard)

A unified, high-performance web dashboard merging the ZKTeco Biometric Attendance System with an IT Helpdesk and AD Console. Built entirely with Vanilla HTML, CSS, and JavaScript — no build step required.

Overview

The ERP Console connects to two primary backends:

  1. ZKTeco Local Server — Python/Flask API (v2.2) handling local biometric hardware, SQLite employee databases, attendance logs, messaging, ticketing, and all admin functions.
  2. Google Apps Script (GAS) — Cloud backend managing IT Helpdesk tickets, token queues, Drive storage, and GAS-side authentication.

It features full PWA support, offline punch caching via IndexedDB, four UI themes, and a built-in suite of IT networking and utility tools.

👥 Human Resources & Attendance

📡 Hardware Management (ZKTeco)

📊 Reporting & Notifications

🎫 IT Services & Collaboration

🆘 SOS Emergency Broadcast

🔧 Admin & Database Tools

🧰 Built-in IT Toolkit

A comprehensive suite of client-side utilities built into the app — no server calls required:

🛠️ Tech Stack

Layer Details
Backend Python 3.8+, Flask, SQLite (WAL mode), pyzk for device communication
Real-time Flask-SocketIO (WebRTC VoIP signaling), Server-Sent Events (SSE) for live refresh and SOS alerts
Frontend HTML5, CSS3 (Native CSS Variables + 5 built-in themes), Vanilla JavaScript (ES6+), 22 modular JS files
Offline Storage localStorage for settings; IndexedDB + Service Workers for offline punch caching
External Libraries (CDN) JsBarcode, qrcode.js, pdf-lib, SheetJS / xlsx, Chart.js, Socket.IO
Notifications Telegram Bot API, Gmail SMTP (SSL)
Cloud Backend Google Apps Script (GAS) for ticketing, Drive, and token queues

🎮 Demo Mode

Don’t have the backends set up yet? Click “🎮 Enter Demo Mode” on the login screen to explore the full UI with mock employees, tickets, devices, and attendance data — no server required.

🔒 Security Notes

Author: Hashiq V H