Getting Biometric Attendance From an Office LAN Into a Cloud HR System

The problem: the clocks were on the wrong side of the firewall

A hotel runs on shifts. Front office, housekeeping, kitchen, security — people arriving at 06:00, at 14:00, at 22:00, some of them clocking out on a different calendar day from the one they clocked into. Attendance is not an HR formality there. It is the input to payroll.

The client already had the hardware: ZKTeco fingerprint terminals, mounted by the staff entrance, working fine. What they did not have was anything to do with the data. Someone exported it, someone re-keyed it into a spreadsheet, and once a month someone reconciled that spreadsheet against a roster that had changed twice since.

The obvious fix is a cloud HR system. The obvious fix does not work, for a reason that kills most of these projects before they start: the terminals are unreachable. A ZKTeco device sits on the office LAN with a private address like 192.168.1.201 and speaks a raw socket protocol on port 4370. A server on the internet has no route to that address. A serverless function cannot hold that socket open even if it did.

That is the wall. This page is mostly about how the system gets over it, and what it does with the punches once they arrive.

How do you get attendance off a device that has no route to the internet?

You stop trying to reach in, and you push out instead.

zk-agent is a small command-line program that runs on a PC in the office — the same network as the terminals, on whatever machine already stays switched on. It reads punches locally and forwards them over HTTPS to the application.

K50-A ──4370──┐
              ├─► ZK Agent (office PC) ──HTTPS──► Codech HR
K50-A ──ADMS──┘

It is 291 lines of plain JavaScript with exactly one runtime dependency. That is a deliberate constraint, not a boast. This program runs unattended on a client's office PC, on a machine nobody administers, for years. Every dependency is a future breakage on a computer I cannot see.

It supports both transports the hardware offers, because different sites need different ones:

• AGENT_PULL — the agent dials the terminal on an interval, default 300 seconds. Works with any device, needs no device configuration.
• DEVICE_PUSH — the agent runs a small HTTP listener on the LAN and accepts the terminal's own ADMS ("Cloud Server") pushes, then forwards them. Lower latency, but the device has to be configured for it.

The mode is a per-device setting in the database, not a deployment decision, so switching a site from one to the other is a dropdown.

There is one more command, and it matters more than it looks: probe. It connects to the terminal, prints how many users and logs the machine is holding and the last few punches, and changes nothing. It is the mandatory first step of every install, because the alternative is discovering a wrong IP address at the same moment you discover a mangled sync. The README pairs it with a symptom-to-cause table for the two failures that account for almost all of them: a timeout means the wrong IP or a different subnet, a refusal means the wrong port.

What happens when the office PC drops its connection mid-sync?

Nothing is lost, and nothing is counted twice.

The agent sends punches in chunks of 200, oldest first, and keeps a cursor on disk. The cursor advances only after the server confirms the batch — never before. If the connection dies halfway through, the cursor is still pointing at the last confirmed position, and the next run re-sends from there.

That means the agent will sometimes send the same punch twice. It does this on purpose. When it cannot tell whether a batch landed, it re-sends rather than skips, because the ingest endpoint is idempotent and a duplicate costs nothing, while a skip costs somebody a day's pay.

Two more behaviours make it survivable in a real office:

• Failed syncs back off exponentially, from 30 seconds to a five-minute ceiling. A terminal switched off at night cannot spend eight hours hammering the office network and the API.
• When there are no new punches, it still POSTs an empty batch. That empty POST is a heartbeat, and it is the only way the server can tell a quiet terminal from a dead agent. Without it, "no data" is ambiguous — and an ambiguous silence in an attendance system gets read as "everyone was absent".

Why a duplicate punch is a payroll bug, not a display bug

People press the sensor twice. They press it, get no beep, press it again. On a shared terminal at shift change, with thirty people queuing, this happens constantly.

If two punches survive into the attendance record, one of two things follows: an employee is paid for a shift they did not work, or a check-in is paired with the wrong check-out and the day silently doubles. Neither surfaces as an error. Both surface on payday.

Defence is three layers deep:

1. The database refuses it. A composite unique constraint on (organizationId, deviceId, biometricId, punchedAt, punchType), plus a second unique on the device's own log id. Bulk inserts run with skipDuplicates, so a replayed batch is absorbed rather than rejected — which is precisely what makes the agent's re-send-when-unsure policy safe.
2. A time window collapses near-identical punches. One administrator-set number, and it governs both the terminal path and the web check-in path. Two settings would drift, and the drift would only be discovered in a payroll dispute.
3. The fallback is a real value, not nothing. A tenant with no policy row configured falls back to a shared five-minute default — not to "no deduplication at all". Unconfigured must never mean unprotected.

Raw punches are stored in a table the schema describes as immutable: never edited, never deleted. Everything downstream is derived. If the calculation is wrong, it can be re-run against the original evidence rather than against a previously corrected guess.

Which day does a shift that ends at 6am belong to?

This is the question that separates attendance software that works from attendance software that mostly works.

A night porter clocks in at 22:00 on Tuesday and out at 06:00 on Wednesday. Those eight hours belong to Tuesday's shift. A punch at 01:00 belongs to yesterday. Get this wrong and every night-shift employee's timesheet is split across two days, every one of them looks half absent, and the error is invisible until somebody is underpaid.

The system answers it in one pure function used by every caller — the processor, the reports, the payroll run — resolving four tiers, highest first:

1. A one-day shift override (someone covering a single shift).
2. A date-ranged roster assignment.
3. The employee's default shift.
4. The organisation default.

Overnight handling then appears in three separate places, because it is three separate problems:

• The business date a punch belongs to — with a 120-minute post-shift cutoff, so a 06:40 exit from a shift that ended at 06:00 still lands on the right day.
• The scheduled duration — computed as 1440 - start + end when the shift crosses midnight, rather than the negative number the naive subtraction gives.
• The check-in window — which legitimately opens on one calendar day and closes on the next.

Local wall-clock times convert to UTC through an iterative offset-correcting routine, up to four passes, so the conversion lands correctly on daylight-saving boundaries instead of an hour out twice a year. It is exported as the codebase's single answer to that question, so a second implementation cannot quietly drift from the first.

A working day is modelled as explicit in/out pairs, not a first-punch/last-punch subtraction. Time spent off-site between punches is not paid. The pairing logic handles declared check-ins, declared check-outs, and undeclared punches — which alternate, because most terminals do not record direction reliably.

Why changing someone's roster must not rewrite last month's pay

Roster assignments are effective-dated. Re-running the processor over June resolves June's roster, not today's.

This sounds like a detail. It is the difference between a system you can trust and one you cannot. Move a night-shift worker onto days in August, and a system without effective dating will re-evaluate July's 22:00 arrivals against the day shift and mark a month of punctual work as late. Nobody notices until a manager is asked to explain a disciplinary record that the software invented.

Overlapping assignments are deliberately allowed, because an overlap is what a roster edit looks like mid-edit, and refusing to save one just teaches managers to work around the system. Overlaps resolve deterministically instead.

How do you sell the same HR system to more than one company?

Multi-tenancy at the data layer, not one database per customer.

Isolation is enforced by a Prisma extension that rewrites query predicates before they reach the database, across twelve intercepted operations, backed by an organisation column on every scoped model and enforced by unique constraints scoped to the tenant — a biometric id is unique within a company, not globally. There are 196 tenant-scoping references across 35 files.

On top of that sits module licensing in two layers, which is what makes payroll sellable rather than merely built:

• ModuleEntitlement — per organisation, controlled by the platform. Whether this client has bought payroll at all.
• ModuleGrant — per user, controlled by the client's own owner. Which of their people may open it.

Both gates must pass. The design point is the one a buyer asks about second: the platform's own super-admin cannot approve another company's payroll. Access control is a rank comparison with strict inequality, so a role cannot act on its own level, and cross-tenant platform access is written to the audit log before the session is issued.

What the system refuses to pretend

The most useful engineering in this build is where it declines to say something it cannot prove.

A device is ONLINE only if an agent reported for it recently. Staleness is derived at read time from the device's own sync interval, not stored as a flag someone forgot to clear. An operations team that finds a dead terminal showing a green badge stops trusting the badge, and then stops checking the screen at all.

A day off does not render as a failed sync. Empty states show as empty, not as sample data, and not as an error.

Payroll figures are DECIMAL(14,2), never floats. Money is not a floating-point number.

That posture is also why this page has no uptime figure, no performance benchmark and no user count in it. See the last section.

What isn't built yet

Five things worth naming.

Payroll is deliberately a core run. It computes from attendance, and that is all. There is no tax calculation, no provident fund, no gratuity, no bank disbursement file. Those are jurisdiction-specific and doing them badly is worse than not doing them.

The device agent has no automated tests of its own. It is four files, and its correctness rests on the idempotent ingest contract on the server side rather than on a suite around the agent. The ingest endpoint is tested; the agent is not.

A security-hardening backlog is open and explicitly deferred. Rate limiting, response security headers and pre-parse request size guards are specified and scheduled, not shipped. This page therefore does not describe the system as hardened, and no reader should infer it.

There is no production telemetry of any kind — no analytics, no APM, no error tracking, no load test.

Self-serve tenant onboarding does not exist. Creating an organisation is a platform-admin action today.

A note on these numbers

Every figure on this page was counted from shipped code or produced by running the test suite on 18 August 2026. Nothing came from a planning document — several of this project's own internal docs have drifted from the code, and where they disagree, the code won.

The numbers describe what was built, not how it performs in production. There is no load test, no uptime record and no analytics behind any of it, so there are no performance, availability or scale claims here at all. The dataset the system has been exercised against is a seeded demonstration tenant, not a year of a hotel's real operations.

The delivery figure — 13 calendar days from first commit to a deployed platform, across 227 commits and 86 merged pull requests — is measured from git history. The test figures come from running the suite, not from a coverage estimate. Where a number would have been flattering but unverifiable, it is not here.