Engineering · ArbeitszeitCheck
Anatomy of an offline stamp
12:07, a construction site gate, no bars. The worker clocks in anyway. Here is everything that stamp goes through before it lands in the timesheet, and where it could have gone wrong.
Minute zero: the phone can't reach the server
The mobile app doesn't retry blindly and it doesn't fake success. The stamp goes into an encrypted FIFO queue on the device, AES-GCM ciphertext in AsyncStorage, with the data key held in SecureStore. That last detail has a real reason: SecureStore caps values at roughly two kilobytes on Android, so the obvious design (queue in SecureStore, done) was never available. The queue itself is capped at 32 entries, a bounded buffer, not an infinite promise. Optimistic status shows the worker "clocked in" immediately; the queue drains when coverage returns.
Draining is deliberately fussy: the app snapshots the queue under a mutex, does the network work outside the lock, then merges the result back, so a stamp enqueued during a drain isn't overwritten by the merge. This is the class of bug you only find by being paranoid about concurrent writes.
The replay: claim before you mutate
When the stamp finally reaches the server it carries two things a normal stamp doesn't: a clientRequestId and an occurredAt timestamp. The server doesn't apply it directly. It first writes a claim row"this request id is now mine, result pending." Only then does it mutate the timesheet. If two retries race, the second one finds the claim already taken and gets the first attempt's outcome instead of a double stamp.
The claim row carries a payload_hash, sha256 over the action and its normalized inputs. Same request id with a different payload answers 409, not a silent overwrite: a client that retries "clock in" and accidentally resends "clock out" gets an error it can see, not corrupted data. Claims left pending for more than 300 seconds are reclaimed; the whole replay window is seven days, after which a cleanup job deletes the rows.
Whose clock counts
Phone clocks drift and can be set backwards deliberately, so compliance is evaluated at occurredAt, the moment the worker actually stamped, not at arrival time. How far the server will trust that timestamp is a bounded admin setting: configurable skew between 24 and 72 hours back, five minutes into the future. The ceiling is deliberate; a stamp "from last Thursday" needs a human to look at it, not an algorithm to believe it.
The kiosk path gets the same contract with its own wrinkles: an encrypted NFC badge cache (seven-day TTL, capped at 500 entries) so a hallway terminal in a basement still opens the right action screen during an outage, and a successful drain writes the new status back into that cache, otherwise the next outage would offer the worker actions that are already wrong.
What's still missing, on the record
Two gaps. A stamp that fails permanently stays in the queue flagged failed, the user sees a toast, but there's no per-row retry UI yet. And old app versions that don't know the new fields simply clock online-only; nothing breaks, they just lose the feature. Both are written down in the decision doc because the worst kind of limitation is the one nobody documented.
The full decision record, including the lock ordering and the cleanup job, lives in the repository the AGPL guarantees you can read. That's the other half of this post's answer: the queue isn't just engineered to survive a dead zone, it's documented so you can check that it is.