Biometrics System Architecture

1. System Architecture & Network Topology

The system uses separate paths for biometric attendance data and employee identity data. Physical biometric terminals communicate with a Python/Flask bridge service running on the internal spark host. The bridge retrieves attendance records from the terminals and persists them in a local SQLite database. The web portal accesses the bridge API through the configured Cloudflare Tunnel. Separately, the portal queries the Teams Directory Worker on Cloudflare to obtain employee records from Cloudflare D1.

2. Python Biometric Bridge Service

The biometric bridge is implemented in Python using Flask and the zk library. The application defines two physical biometric devices and exposes REST endpoints on local port 5001. CORS is enabled by the application to permit browser-based frontend access.

Device Configuration

Database Initialization

On application startup, init_db() creates the SQLite database file attendance.db if it does not already exist and creates the logs table. The database path is relative to the application's current working directory.

The unique constraint on device_ip, user_id, and timestamp, combined with INSERT OR IGNORE, prevents the same punch record from being inserted more than once for the same device, user, and timestamp.

Live Synchronization Endpoint: GET /api/get-logs

When requested, the endpoint loops through both configured scanners. For each device it creates a ZK connection with a four-second timeout, retrieves attendance records using get_attendance(), disconnects, and attempts to persist the returned records into SQLite. The endpoint then returns the retrieved records and device status as JSON.

Historical Endpoint: GET /api/get-history

The historical endpoint reads records from the local SQLite logs table. If a date query parameter is supplied in YYYY-MM-DD format, the endpoint filters timestamps beginning with that date. Without a date parameter, it returns all stored records.

3. Cloudflare Tunnel & API Exposure

The local Flask service listens on port 5001 on the spark host. The configured Cloudflare Tunnel provides the external HTTPS route used by the web portal to reach that local service through biometric-api.cbposervices.com.

4. Teams Directory Worker & Employee Identity Mapping

The Biometrics frontend uses the Teams Directory Worker to retrieve employee directory records from Cloudflare D1. The directory provides the employee information needed to translate biometric numeric user_id/CID values into employee names.

The Teams API code reviewed for this architecture includes GET operations for employee records, dropdown options, and activity logs, plus a POST / operation that creates or updates an employee record and writes an activity log. It is therefore more accurate to describe the backend as supporting create/update operations, rather than calling it "full CRUD."

5. Frontend Application Flow

A. Page Initialization CURRENT

B. Live Snapshot CURRENT

C. Historical Review CURRENT

D. Employee Management BACKEND CAPABILITY

6. Network & Service Summary

7. Current Functionality & Scope

8. Operational Notes

• Service startup: The Python application calls init_db() before starting Flask when executed directly.
• Windows service deployment: If the application is managed through NSSM on spark, NSSM is a deployment/runtime management layer rather than part of the Python application itself.
• Scanner connectivity: The bridge uses a four-second ZK connection timeout for each configured scanner.
• Database location: attendance.db is a relative path in the Python source. Its actual filesystem location depends on the process working directory.
• CORS: The current Python application enables Flask-CORS globally. Production access control is therefore dependent on the surrounding network/tunnel/security configuration as well as the application itself.

9. Architecture Boundaries & Assumptions

• The Python bridge is responsible for scanner communication and attendance persistence; it does not own employee profile information.
• Employee identity data is maintained separately through the Teams Directory Worker and Cloudflare D1.
• The biometric API returns machine-readable attendance data; the portal is responsible for presentation and identity resolution.
• The Cloudflare Tunnel configuration is outside the Python source and should not be inferred beyond the known public API route.
• The current documentation describes the implementation reviewed in August 2026. Future management UI or additional endpoints should be reflected in a subsequent revision.

10. Document Revision History