Edge Attendance Gateway

Attendance at the branch edge

Attendance devices and mobile workers cannot always depend on a stable route to cloud ERPNext. Edge Attendance Gateway places a small local control point at the branch, factory, warehouse, or work site so a check-in can be verified and queued near its source before it is sent upstream.

System responsibilities

The HRMS client discovers a reachable gateway over LAN or NetBird and sends the attendance payload. The gateway validates the site identity and cryptographic proof, writes accepted events to a durable SQLite queue, and forwards pending records to ERPNext when connectivity returns. ERPNext remains the durable HR system and final business-record boundary.

Request and sync flow

1. The employee initiates a check-in from the HRMS PWA or mobile workflow.
2. The gateway validates client network access, site identity, timestamp, nonce, sync ID, and HMAC-SHA256 signature.
3. The accepted event is written to SQLite before upstream delivery is assumed.
4. A scheduled retry worker sends pending records to the ERPNext REST API.
5. The edge_attendance_guard Frappe app validates the signed request before creating Employee Checkin.
6. The gateway records a synced, retryable, or permanent failure for operators.

Security model

• HMAC-SHA256 binds a check-in to the configured site secret.
• sync_id and nonce support idempotent, replay-aware delivery.
• ERPNext performs a second server-side guard before insertion.
• Invalid signatures and unknown site identities are rejected instead of entering the trusted queue.
• One protected shared secret is used per gateway/site and must never be placed in source or logs.
• Trusted proxy boundaries preserve the original client IP across Traefik, LXD, or Nginx hops.

Implementation

The backend is FastAPI with SQLite persistence, WAL mode, queue state, retry counts, audit logs, and a background sync loop. The operations console is Next.js. Docker Compose runs the backend and frontend; host networking is used deliberately so branch clients can reach the local gateway address.

Failure behavior

If ERPNext is unavailable, the event remains queued locally for retry. A successful local acceptance is not presented as a successful ERPNext insertion until synchronization is confirmed. Queue age, failed records, and audit entries remain visible so operators can distinguish local availability from upstream completion.

Current status and deployment boundary

This is a building project and an operational starting point, not a claim of universal attendance hardware support. Deployment requires a Linux edge host, Docker, a reachable ERPNext API, the edge_attendance_guard app, protected site configuration, and a LAN or NetBird path. The SQLite queue should be backed up before upgrades or destructive maintenance.

Technical references

Source repository: edge-attendance-gateway. Read the README, session log, and proxy guide.

Ecosystem position

Edge Attendance Gateway is the edge-operations layer connecting the HRMS node ecosystem to physical attendance workflows. It complements the n8n2erpnext HRMS Nodes rather than replacing ERPNext HRMS.