DEV Community: Lakshay Tyagi

What 6 Months in Production Taught Me About Biometric Gate Control: Race Conditions, Ghost Fingerprints, and Building a System That Actually Works

Lakshay Tyagi — Sat, 10 Oct 2026 05:11:23 +0000

A follow-up to my previous two posts on connecting a ZK fingerprint device to Rails. This one is about what actually broke in production, how I found it, and what I rebuilt from scratch.

When I published the second biometric post, I genuinely believed the system was solid. Gate control working. Enrollment from the browser. Auto-start on boot. Android backup bridge. The whole thing.

Then the client called.

Expired members were walking in. The dashboard showed DENIED. The door opened anyway. And when I looked at the code — really looked at it — I found the line that explained everything:

from sync_access import sync_device_access  # commentthis

Gate control had never run in production. Not once. Every DENIED label in the dashboard for six months was cosmetic. The door opened for everyone who had a fingerprint on the device, expired subscription or not.

This post is about what I found, what I broke while fixing it, and what the system actually looks like now.

The Mental Model Most People Get Wrong

Before anything else, I need to explain something that took me an embarrassingly long time to fully internalize: the Rails app does not control who enters the gym.

There are two completely separate systems operating independently:

System 1 — The physical gate (device-enforced, zero internet dependency)

The ZK fingerprint device has a door relay connected to it. When someone scans their finger, the device runs a match against the fingerprint templates stored in its own internal flash memory. If it finds a match — green light, relay fires, door opens. If it doesn't — red light, door stays closed.

The device has no knowledge of subscriptions, member names, your database, or the internet. It does not make HTTP requests. It does not check anything in Rails. It simply asks: "do I have a template that matches this finger?" That's the entire decision. Even if Rails is down, Railway is down, the laptop is off, the internet is cut — if a template exists on the device, the door opens.

System 2 — Attendance recording (Rails, happens after the door decision)

After the device fires (or doesn't), the Python bridge picks up the punch and sends it to Rails. Rails looks up the biometric mapping, checks the subscription, and records the attendance as ALLOWED or DENIED. This is purely record-keeping. The door has already opened or stayed closed before this code runs. Rails cannot retroactively close a door.

This distinction matters enormously because it means:

trn_member_biometric_mappings does not allow or deny anyone. It's a lookup table. It answers one question: "which gym member does this fingerprint slot belong to?" That's all.
trn_member_subscriptions does not control the gate. It tells you who has an active subscription. The gate doesn't know it exists.
sync_access.py is the only bridge between the two systems. It translates "subscription expired in Rails DB" into "template deleted from device memory." Without it running, the two systems diverge silently.

The complete lifecycle of one member looks like this:

Enrolled
  → template written to device flash memory
  → DB row created: mbm_is_active='Y', mbm_finger_template=NULL
  → NULL is correct — template is ON device, not backed up yet
  → door opens when they scan ✅

Subscription active
  → sync runs every 60 seconds
  → device_audit returns access=ALLOW
  → sync does nothing
  → template stays on device, NULL stays in DB
  → door opens ✅

Subscription expires
  → sync runs
  → device_audit returns access=DENY
  → sync saves template bytes to DB (mbm_finger_template = JSON)
  → sync deletes user from device (conn.delete_user)
  → template no longer in device memory
  → door stays closed ❌

Member renews
  → sync runs
  → device_audit returns access=ALLOW
  → member not on device but has stored template
  → sync restores template from DB back to device
  → door opens again ✅

mbm_finger_template is NULL for every active member. That's not a bug. It's correct. The template lives on the device. It only moves to the DB right before deletion, so it can be restored on renewal. The DB is a backup, not the primary store.

Gate Control Was Never Running

Back to the commented-out line.

sync_device_access() was disabled in bridge.py during development and never re-enabled before going live. The midnight scheduler thread was starting, running its loop, and doing nothing. For six months.

The first thing I did after re-enabling it was run with --dry-run to see what it would actually do:

Sync complete. Allowed=48, Blocked=0, Orphans=153

Wait. 153 orphans? Those are fingerprint slots on the device with no DB mapping — remnants of manual enrollments, test users, people enrolled before the software existed. And Blocked=0 even though I knew there were expired members?

The dry-run showed nothing to block because of the second bug.

The Sync Blind Spot

Blog 2's sync_access.py looped over mbm_is_active='Y' rows from the DB and checked each one against the device. Logical, but fatally flawed.

When a member re-enrolls, Step 1 of enrollment deletes their old fingerprint slot from the device. Step 2 sets their old mapping to mbm_is_active='N'. Step 3 creates a new slot, Step 4 saves a new active mapping.

The old mapping disappears from the sync's view — it only looks at active rows. But here's the problem: Step 1 runs against the device, but sometimes the old slot had already been deleted in a previous partial enrollment attempt. In those cases, the old slot never got cleaned up properly, or a duplicate slot from an even older enrollment was still sitting on the device.

The result: a member could have multiple fingerprint slots on the device. Sync only knew about the current active one. Old slots — "ghost fingerprints" — were invisible. When a subscription expired, sync blocked the current slot. The ghost slots stayed on the device. The member could still enter with an old finger.

The fix required a completely different approach. Instead of asking the DB "which members exist and are they on the device?", ask the device "which fingerprint slots exist and what's their status?"

New device_audit Rails endpoint returns all mappings — active and inactive — each tagged with is_active_mapping: true/false and access: ALLOW/DENY. The rewritten sync_access.py now walks conn.get_users() (every slot physically on the device), looks each one up in the device_audit results, and acts accordingly:

# PASS 1: walk every fingerprint on device
for user in device_users:
    if user.privilege == 14:
        continue  # never touch staff/admin accounts

    mapping = mappings_by_device_user_id.get(str(user.user_id))

    if not mapping:
        orphan_count += 1
        continue  # no DB record for this slot — leave it alone

    if mapping["access"] == "DENY":
        # save template first, delete second
        save_template_to_rails(...)
        conn.delete_user(uid=user.uid)

# PASS 2: restore anyone who renewed but isn't on device
for mapping in all_mappings:
    if mapping["access"] == "ALLOW" and not on_device and has_template:
        restore_user_to_device(conn, mapping)

After the fix, running the real sync for the first time: 93 expired members blocked in one pass. Ninety-three fingerprints that had been opening the door for months, gone in a single sync cycle.

Two-Phase Save/Delete — The Safety Guarantee

Blog 2's sync had a silent data loss risk:

save_template_to_rails(device_user_id, uid, templates)  # might fail
conn.delete_user(uid=user.uid)  # runs regardless

If the network dropped between these two lines — timeout, cold start on Railway, anything — the template was gone forever. The member's fingerprint was deleted from the device with nothing saved to the DB. No restore possible. Manual re-enrollment required, meaning the member had to physically come in.

The fix is small but critical. save_template_to_rails() now returns True or False:

def save_template_to_rails(device_user_id, uid, templates):
    try:
        response = requests.post(
            f"{RAILS_API_BASE}/api/biometric_mappings/save_template",
            json={...},
            timeout=60
        )
        if response.status_code == 200:
            return response.json().get("status") == True
        return False
    except Exception as e:
        print(f"Template save failed: {e}")
        return False

And the delete only happens if the save was confirmed:

if user_templates and mapping["is_active_mapping"]:
    saved = save_template_to_rails(device_user_id, user.uid, user_templates)
    if not saved:
        print(f"SKIPPED — template save failed, will retry next sync")
        continue  # skip the delete entirely

conn.delete_user(uid=user.uid)

If the save fails, the member is skipped. Their finger stays on the device. The next sync cycle (60 seconds later) tries again. Eventually it succeeds. No data lost.

This is the most important safety property of the system: a subscription expiring cannot cause template loss under any failure condition. Internet down → sync skips, finger stays on device. Bridge down → device untouched. Railway cold start kills the save request → template save returns False, delete skipped, retry next cycle. The only way a template disappears is if the save succeeds AND the delete succeeds.

The Enrollment Race Condition

This section is the one that cost the most debugging hours.

The enrollment flow in Blog 2 computed the next uid like this:

def get_next_uid_and_user_id(conn):
    users = conn.get_users()
    max_uid = max(u.uid for u in users)
    max_user_id = max(int(u.user_id) for u in users)
    return max_uid + 1, str(max_user_id + 1)

Simple. Reasonable. Completely wrong in production.

conn.enroll_user() puts the device into "waiting for scan" mode and returns immediately. The actual fingerprint capture happens whenever the person physically places their finger on the scanner — which could be 5 seconds or 5 minutes later. During that waiting period, conn.get_users() may not show the pending user at all, because no template has been committed yet.

Incident 1 — Concurrent enrollments:

Staff clicked Enroll for member A. Device showed "scan now." Before A scanned, staff clicked Enroll for member B. get_next_uid_and_user_id() called conn.get_users(). A's pending slot wasn't visible. Both A and B computed the same next uid. Both got assigned, say, uid=321. Whoever scanned first "won" the slot. The other person got a mapping pointing to someone else's fingerprint.

In one session, four members ended up sharing uid=321. All four rows in the DB pointing to the same physical slot, one person's actual fingerprint stored there, three others with ghost mappings. Manual cleanup required for all four.

Incident 2 — Process restart between enroll and scan:

Staff clicked Enroll. Before the member scanned, enroll_api.py was restarted to apply a code change. (Critical lesson learned painfully: saving a .py file does NOT update a running Python process. You must stop it and start it again.) The in-memory _last_issued counter reset to zero. The next enrollment computed the same uid as the pending-but-unscanned slot. Collision.

Incident 3 — Old seed data invisible to the DB query:

The max_ids endpoint filtered by mbm_device_sn. Old seed rows from before the system existed had blank or different mbm_device_sn values. They were invisible to the query. max_ids returned 456 as the maximum. An old seed row had device_user_id=457. New enrollment also got assigned 457. Collision.

Three different root causes, same symptom: duplicate uid assignment, ghost mappings, wrong attendance attributed to wrong members.

The fixes, in order of attempt:

Per-member locks — didn't help. Two different members enrolling concurrently still computed the same uid.
Global enrollment lock + _last_issued in-memory counter — fixed concurrent enrollments, but _last_issued reset to zero on every restart.
max_ids endpoint — fixed restart case, but old seed data with wrong device_sn was invisible.
Allocator table with FOR UPDATE row locking — correct final fix.

The allocator table:

CREATE TABLE biometric_id_allocations (
  id INT AUTO_INCREMENT PRIMARY KEY,
  allocation_compcode VARCHAR(12) NOT NULL,
  allocation_device_sn VARCHAR(50) NOT NULL,
  allocation_next_uid INT NOT NULL,
  allocation_next_device_user_id INT NOT NULL,
  created_at DATETIME,
  updated_at DATETIME
);

Every enrollment calls POST /api/biometric_mappings/allocate_ids. Rails runs:

ActiveRecord::Base.transaction do
  row = BiometricIdAllocation
    .lock("FOR UPDATE")
    .find_or_create_by!(
      allocation_compcode: compcode,
      allocation_device_sn: device_sn
    )

  uid = row.allocation_next_uid
  device_user_id = row.allocation_next_device_user_id

  row.update!(
    allocation_next_uid: uid + 1,
    allocation_next_device_user_id: device_user_id + 1
  )
end

render json: { status: true, uid: uid, device_user_id: device_user_id.to_s }

FOR UPDATE locks the row for the duration of the transaction. Two concurrent enrollments cannot both read the same counter value — the second one waits until the first commits, then reads the already-incremented value. Atomic. DB-backed. Survives restarts. Survives concurrent calls. Survives half-enrolled limbo states. No more collisions by construction.

The global enrollment lock is kept alongside it as defense-in-depth — returns HTTP 429 "please wait" if another enrollment is physically in progress — because even with a safe counter, you don't want two people standing at the device simultaneously.

The enrollment function in Python became one line change:

# Before
new_uid, new_device_user_id = get_next_uid_and_user_id(conn)

# After  
new_uid, new_device_user_id = allocate_next_ids(compcode)

Where allocate_next_ids is:

def allocate_next_ids(compcode):
    resp = req.post(
        f"{RAILS_API_BASE}/api/biometric_mappings/allocate_ids",
        json={"compcode": compcode, "device_sn": DEVICE_SN},
        timeout=15
    ).json()
    return resp["uid"], resp["device_user_id"]

Everything else in enrollment — delete old finger, deactivate old mapping, create device user, trigger scan, save new mapping — stayed exactly the same. One line swap. No race conditions.

The Bugs Nobody Talks About

While debugging the race condition, three other silent bugs surfaced.

deactivate_all silently doing nothing:

During re-enrollment, Python sent member_id as an integer in the JSON payload. The DB column mbm_member_id is varchar(4). Rails compared WHERE mbm_member_id = 291 (integer) against '291' (string). Zero rows updated. No error thrown. The old mapping stayed active. The member ended up with two active mappings — the old finger still worked after re-enrollment.

Fix: explicit .to_s.strip in the Rails controller, str(member_id) in Python. One line each.

save_template writing to the wrong row:

When a member had both active and inactive mappings with the same device_user_id (from a failed re-enrollment), find_by returned the first match — often the deactivated old row (lowest id). The template bytes got saved to the wrong row. The active mapping stayed with template=NULL. When the member's subscription expired and sync tried to block them, it found no template to save, skipped the backup, and either left them on the device or deleted them without backup depending on the code path.

Fix: added mbm_is_active: 'Y' to the find_by lookup. Now it only matches the active mapping.

mbm_is_active='N' from birth:

If enrollment fails after Steps 1+2 (old finger deleted, old mapping deactivated) but before Steps 3+4 complete (new device user created, new mapping saved), the system creates a mapping row with mbm_is_active='N' and mbm_finger_template=NULL. The member has a valid subscription but no working fingerprint. The frontend shows "No fingerprint enrolled." Door stays closed.

This is only detectable by querying:

SELECT m.*, s.ms_end_date 
FROM trn_member_biometric_mappings m
JOIN trn_member_subscriptions s ON s.ms_member_id = m.mbm_member_id
WHERE m.mbm_is_active = 'N' 
AND m.mbm_finger_template IS NULL
AND s.ms_end_date >= CURDATE();

Any rows returned are members with active subscriptions and no working fingerprint. Fix: re-enrollment.

Operational Changes

Sync timing — midnight to 60 seconds:

A member who renews their subscription at 2pm shouldn't have to wait until the next morning for the door to work. Sync now runs every 60 seconds. Worst case wait after renewal: 60 seconds. In practice, under a minute.

Device clock sync on startup:

The ZK device has its own internal clock. If it drifts, attendance timestamps are wrong — and the bridge's today-only filter might discard punches that are actually today. Bridge.py now syncs the device clock from the laptop on startup:

def sync_device_time(conn):
    try:
        conn.set_time(datetime.now())
        print(f"Device time synced to {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
    except Exception as e:
        print(f"Could not sync device time: {e}")

The laptop syncs automatically with Windows time servers. The device syncs with the laptop every time the bridge restarts. Clock drift eliminated.

Bridge heartbeat and dashboard indicator:

Bridge.py now pings POST /api/bridge_heartbeat every 5 minutes. A new trn_bridge_heartbeats table stores the last-seen timestamp per device. The dashboard shows a dynamic bridge status banner — green if last heartbeat was within 10 minutes, orange if within an hour, red if longer.

The banner auto-updates every 30 seconds via AJAX without page refresh. When the bridge goes offline and staff restart it, they watch the banner flip from red to green on its own.

Offline state shows exactly what to do:

"Biometric Bridge is OFFLINE — Go to gym laptop → double-click 'Restart Biometric Bridge' on Desktop → wait 30 seconds"

restart_bridge.bat on the Desktop:

@echo off
taskkill /F /IM python.exe /T >nul 2>&1
timeout /t 2 /nobreak >nul
start "" /B cmd /c "cd /d C:\Users\Admin\Desktop\biometric_bridge && python bridge.py" >nul 2>&1
start "" /B cmd /c "cd /d C:\Users\Admin\Desktop\biometric_bridge && python enroll_api.py" >nul 2>&1
echo Bridge restarted. Wait 30 seconds then check dashboard.
pause

One double-click. No terminal. No Python knowledge. Staff can handle it.

Device and DB reset scripts:

Two utility scripts written for production operations:

cleanup_selective.py — reads a CSV with a keep column, deletes everyone not marked from the device. Used twice: once when 179 accumulated ghost users needed clearing, once for a full client-requested reset keeping only 5 people (admins and owners).

deactivate_orphaned_mappings.py — after a device wipe, queries device_audit and deactivates DB rows pointing to slots that no longer exist on device. Keeps DB and device in sync after bulk operations.

Why Enterprise Systems Don't Have These Problems

Brief and honest: eSSL, ZKTeco's own software, Gymmaster, and similar systems avoid most of these issues because they use the official ZKTeco Windows SDK (zkemkeeper.dll), not pyzk.

The official SDK has enrollment event callbacks — when a scan completes, an event fires in your application with the template bytes. You save atomically in one step. No fire-and-forget, no polling, no timing window for race conditions.

They also use the ADMS protocol — the device itself initiates an HTTP connection to the cloud and pushes attendance records. No bridge laptop. No polling. I investigated ADMS and got close — DNS worked, port 80 was reachable, Rails controller was deployed — but the router at the gym appears to have per-device firewall rules that block outbound HTTP from the ZK device's MAC address specifically. The laptop and Android phone on the same network work fine. The device can't reach the internet. ADMS code stays in the codebase waiting for a router upgrade.

The enrollment race condition exists because pyzk has no enrollment callback — a fundamental limitation of a community-reverse-engineered library versus the official SDK. The allocator table is the correct workaround within those constraints. It works.

Current State

Enrollment       → allocator table, FOR UPDATE locking, zero collisions
Sync             → every 60 seconds, walks device not DB, 
                   catches all fingerprints including ghosts,
                   two-phase save/delete, retry on failure
Gate control     → device-enforced, internet-independent,
                   template on device = door opens, always
Template safety  → saved before delete, confirmed before delete,
                   retry if save fails, no irreversible loss possible
Monitoring       → heartbeat every 5 min, dashboard indicator,
                   non-technical restart procedure on Desktop
Device clock     → synced to laptop time on every bridge startup

The first sync run after re-enabling gate control blocked 93 fingerprints. Two months later the system has processed thousands of attendance records, correctly blocked expired members, correctly restored renewed ones, and handled two full device resets without data loss.

The notebook with the manual attendance register is still in the drawer. It has not been opened.

Key Takeaways

The hardest bugs aren't the ones that throw errors. They're the ones that silently do nothing while you think everything is working. sync_device_access() commented out. deactivate_all returning updated: 0 with no exception. Template save failing silently and delete running anyway. None of these crashed the system. All of them were invisible until something downstream went wrong.

"Works" and "production-ready" are different things. The system worked in testing. It worked for the first few weeks. The bugs only appear at scale, over time, with real staff who click buttons too fast, real network conditions that drop connections mid-request, and real device firmware quirks that don't show up in controlled environments.

Log everything that matters. deactivate_all called: compcode=SF member_id=291 and deactivate_all: updated 1 rows — two log lines that took 20 minutes to add and saved hours of debugging. If a critical operation can return 0 when it should return 1, log it explicitly. Don't assume.

The device is the source of truth for physical access. Not Rails. Not the DB. The device. Everything else is record-keeping. Get this mental model right and the architecture becomes obvious.

Live: spine-fitness.com | Source: github.com/imlakshay08/spine-fitness-gym-management-system

Part of a series — read the original post and the first upgrade post for full context.

From Polling to Production: How I Upgraded My Biometric Integration with Gate Control, Auto-Enrollment, and 24/7 Reliability

Lakshay Tyagi — Wed, 03 Jun 2026 08:39:56 +0000

A follow-up to my previous post on connecting a ZK fingerprint device to Rails. This is the upgrade story — what broke, what I rebuilt, and what the system looks like now.

👉 Read the original post first: Connecting a Biometric Fingerprint Device to a Rails Web App Using Python

The Problem with "Good Enough"

When I published the first biometric post, the system worked. The Python bridge polled the device, forwarded punches to Rails, attendance appeared on the dashboard.

But "worked" and "production-ready" are different things.

Here's what the system looked like in practice after a few weeks of real gym use:

The bridge only ran when staff remembered to start it. They didn't always remember.
The bridge sent every historical punch on every restart. January records were being re-sent in March.
Expired members could still walk in. The DENIED label in the dashboard was cosmetic — the door opened anyway.
Enrolling a new member required two separate manual operations — entering them in the software, then going to the device and registering their fingerprint, then manually creating a mapping record in the database.
The gym's spare Android phone running the bridge had adware that would randomly kill background processes.
ADMS (the device's built-in cloud push protocol) wouldn't connect — SSL/HTTP mismatch between the ZK firmware and Cloudflare/Render.

None of these were bugs in the traditional sense. The code did what I wrote it to do. The problem was the gap between what the code did and what the business actually needed.

This post is about closing that gap.

What I Built (The Upgrade Summary)

Feature	Before	After
Bridge startup	Manual	Auto-starts silently on Windows boot via VBScript
Historical re-sends	Happened on every restart	Filtered by `date.today()` — today's punches only
Expired member gate access	Door opened, just logged DENIED	Finger template deleted from device — door physically stays closed
Member enrollment	3 manual steps across 2 systems	Single "Enroll Fingerprint" button in member profile
Bridge reliability	Gym laptop (unreliable, staff-dependent)	Dual: laptop (primary) + Android phone (backup)
Cloudflare/Render SSL	ADMS blocked by SSL mismatch	Flexible SSL on Cloudflare — HTTP from device, HTTPS to Render
Finger template backup	None	Templates stored as JSON in DB before deletion
Auto-restore on renewal	None	Sync script restores templates from DB on next run

Part 1: Fixing the "Today Only" Problem

The original bridge used an in-memory last_sent set to deduplicate. This worked within a single session but had a critical flaw: every time the script restarted, the set was empty, so all historical records were re-sent to Rails.

The fix is one line, but it changes everything:

# bridge.py

from datetime import date

while True:
    today = date.today()  # re-evaluated every loop iteration
    attendances = conn.get_attendance()
    device_sn = conn.get_serialnumber()

    for att in attendances:
        # Only process today's records
        if att.timestamp.date() != today:
            continue

        key = f"{att.user_id}-{att.timestamp}"
        if key in last_sent:
            continue

        payload = {
            "compcode": COMP_CODE,
            "user_id": att.user_id,
            "timestamp": att.timestamp.strftime("%Y-%m-%d %H:%M:%S"),
            "device_sn": device_sn
        }
        send_to_rails(payload)
        last_sent.add(key)

    time.sleep(POLL_INTERVAL_SECONDS)

Two important details:

date.today() is called inside the loop, not outside it. This means if the script runs past midnight, it automatically shifts to the new date without a restart.
The deduplication set last_sent still prevents duplicate sends within a session. Rails-side deduplication handles the cross-session case.

The result: restart the bridge at any point during the day and it picks up exactly from today's records. No January punches appearing in May.

Part 2: Auto-Start on Windows — The Silent Background Process

The original .bat file approach had a visible terminal window. Staff would close it. Attendance would stop. Nobody would notice until the owner called.

The fix is a .vbs file placed in the Windows Startup folder:

' start_bridge.vbs
' Place in: shell:startup

Set objShell = CreateObject("WScript.Shell")
objShell.Run "cmd /c cd C:\Users\Admin\Desktop\biometric_bridge && python bridge.py", 0, False
objShell.Run "cmd /c cd C:\Users\Admin\Desktop\biometric_bridge && python enroll_api.py", 0, False

The 0 as the third parameter means hidden window — no terminal, no visible process. Staff can't accidentally close what they can't see.

Both the attendance bridge and the enrollment API (covered later) start silently on every boot.

To verify it's running without a terminal window, check Task Manager → Details tab → look for python.exe. If it's there, the bridge is alive.

Preventing Sleep from Killing the Process

Windows sleep/hibernate will kill background processes even with the VBScript approach. Set these before deploying:

Settings → System → Power & Sleep
  Screen: Never
  Sleep: Never

Control Panel → Power Options → Choose what closing the lid does
  When I close the lid: Do nothing

This is also where you tell staff: "This laptop is the gym's server. Do not close the lid. Do not shut it down." The mystique helps.

Part 3: The Gate Control Problem — Why DENIED Wasn't Enough

The original system logged DENIED in the database when an expired member scanned their finger. But the door still opened. The DENIED label was purely informational — the device itself didn't know anything had changed.

To physically prevent the door from opening for expired members, the change has to happen on the device itself, not in the database.

The ZK device controls the door relay. When a fingerprint is matched, the relay fires and the door opens. If no fingerprint template exists for a user, the device shows a red failure screen and the relay doesn't fire. No template = no access. No middleware required.

This is the cleanest possible implementation: delete the finger template from the device when a subscription expires, and restore it when they renew.

The Database Change

First, add two columns to trn_member_biometric_mappings to store the template data before deletion:

ALTER TABLE trn_member_biometric_mappings
  ADD COLUMN mbm_finger_template LONGTEXT,
  ADD COLUMN mbm_uid INT DEFAULT NULL;

mbm_uid stores the ZK internal UID (different from device_user_id). mbm_finger_template stores the raw finger template bytes as a JSON array so we can restore them later.

The Sync Script

# sync_access.py

from zk import ZK
from zk.user import User
from zk.finger import Finger
import requests
from config import *

RAILS_API_BASE = "https://spine-fitness.com"
DEVICE_SN = "NFZ8253402448"


def get_access_status():
    """
    Fetch all mapped members and their subscription status from Rails.
    Returns list of {device_user_id, access, name, user_info} dicts.
    """
    try:
        # Wake Render from idle before the real request
        requests.get(RAILS_API_BASE, timeout=30)
    except:
        pass

    try:
        response = requests.get(
            f"{RAILS_API_BASE}/api/access_status",
            params={"compcode": COMP_CODE, "device_sn": DEVICE_SN},
            timeout=60
        )
        return response.json().get("users", [])
    except Exception as e:
        print(f"Could not fetch access status: {e}")
        return []


def save_template_to_rails(device_user_id, uid, templates):
    """
    Before deleting a user from the device, save their finger templates
    to the Rails DB so we can restore them on renewal.
    """
    try:
        template_data = [
            {
                "uid": t.uid,
                "fid": t.fid,
                "valid": t.valid,
                "template": list(t.template)  # bytes → list for JSON serialization
            }
            for t in templates
        ]
        requests.post(
            f"{RAILS_API_BASE}/api/biometric_mappings/save_template",
            json={
                "compcode": COMP_CODE,
                "device_user_id": device_user_id,
                "device_sn": DEVICE_SN,
                "uid": uid,
                "templates": template_data
            },
            timeout=60
        )
    except Exception as e:
        print(f"    Could not save template to Rails: {e}")


def restore_user_to_device(conn, user_info):
    """
    Re-add a previously blocked user to the device using their saved templates.
    Called when their subscription is renewed.
    """
    uid = user_info.get("uid")
    device_user_id = user_info.get("device_user_id")
    name = user_info.get("name", "Member")
    templates_data = user_info.get("templates")

    if not uid or not templates_data:
        print(f"    No stored template for {name} — needs manual re-enrollment")
        return

    try:
        user_obj = User(
            uid=int(uid),
            name=name[:24],
            privilege=0,
            password='',
            group_id='',
            user_id=str(device_user_id),
            card=0
        )
        fingers = [
            Finger(
                uid=int(uid),
                fid=t["fid"],
                valid=t["valid"],
                template=bytes(t["template"])
            )
            for t in templates_data
        ]
        conn.save_user_template(user=user_obj, fingers=fingers)
        print(f"    Restored: {name} (device_user_id={device_user_id})")
    except Exception as e:
        print(f"    Could not restore {name}: {e}")


def sync_device_access():
    print("Starting access sync...")

    users_status = get_access_status()
    if not users_status:
        print("No data from Rails — skipping sync")
        return

    # Build lookup keyed by device_user_id
    access_map = {str(u["device_user_id"]): u for u in users_status}

    zk = ZK(DEVICE_IP, port=DEVICE_PORT, timeout=DEVICE_TIMEOUT,
            password=0, force_udp=False, ommit_ping=False)

    try:
        conn = zk.connect()
        conn.disable_device()

        # Snapshot of current device state
        device_users = {str(u.user_id): u for u in conn.get_users()}
        templates = conn.get_templates()
        templates_by_uid = {}
        for t in templates:
            templates_by_uid.setdefault(t.uid, []).append(t)

        for device_user_id, status in access_map.items():
            access = status["access"]       # "ALLOW" or "DENY"
            name = status.get("name", "Unknown")
            user_info = status.get("user_info", {})

            if device_user_id in device_users:
                user = device_users[device_user_id]

                # Never touch admin/staff accounts (privilege=14)
                if user.privilege == 14:
                    continue

                if access == "DENY":
                    # Save templates to DB before deletion
                    user_templates = templates_by_uid.get(user.uid, [])
                    if user_templates:
                        save_template_to_rails(device_user_id, user.uid, user_templates)
                    conn.delete_user(uid=user.uid)
                    print(f"  BLOCKED: {name} (device_user_id={device_user_id})")

                # access == "ALLOW" and user exists on device → nothing to do
                else:
                    pass

            else:
                # User not currently on device
                if access == "ALLOW" and user_info.get("uid") and user_info.get("templates"):
                    # Previously blocked, subscription renewed → restore
                    restore_user_to_device(conn, user_info)

        conn.enable_device()
        print("Access sync complete.")

    except Exception as e:
        print(f"Sync error: {e}")
        import traceback
        traceback.print_exc()
    finally:
        try:
            conn.enable_device()
            conn.disconnect()
        except:
            pass


if __name__ == "__main__":
    sync_device_access()

The Rails API Endpoint

The sync script needs to know who is active and who isn't:

# app/controllers/api/access_status_controller.rb
class Api::AccessStatusController < ApplicationController
  skip_before_action :verify_authenticity_token

  def index
    compcode  = params[:compcode]
    device_sn = params[:device_sn]
    today     = Date.today

    mappings = TrnMemberBiometricMapping.where(
      mbm_compcode:  compcode,
      mbm_device_sn: device_sn,
      mbm_is_active: 'Y'
    )

    users = mappings.map do |m|
      has_active = TrnMemberSubscription
        .where(ms_compcode: compcode, ms_member_id: m.mbm_member_id)
        .where('ms_end_date >= ?', today)
        .exists?

      member = MstMembersList.find_by(id: m.mbm_member_id)

      {
        device_user_id: m.mbm_device_user_id,
        access:         has_active ? "ALLOW" : "DENY",
        name:           member&.mmbr_name || "Unknown",
        user_info: {
          uid:            m.mbm_uid,
          device_user_id: m.mbm_device_user_id,
          name:           member&.mmbr_name || "Unknown",
          templates:      m.mbm_finger_template ? JSON.parse(m.mbm_finger_template) : nil
        }
      }
    end

    render json: { status: true, users: users }
  end
end

And the template save endpoint:

# app/controllers/api/biometric_mappings_controller.rb
def save_template
  mapping = TrnMemberBiometricMapping.find_by(
    mbm_compcode:       params[:compcode],
    mbm_device_user_id: params[:device_user_id],
    mbm_device_sn:      params[:device_sn]
  )

  return render json: { status: false, message: "Mapping not found" } unless mapping

  mapping.update!(
    mbm_uid:             params[:uid],
    mbm_finger_template: params[:templates].to_json
  )

  render json: { status: true }
end

Running Sync Automatically

The sync runs once on bridge startup and once every midnight — embedded as a background thread inside bridge.py:

# bridge.py (updated)

import threading
from sync_access import sync_device_access

SYNC_HOUR = 0  # midnight

def sync_scheduler():
    print("Running initial access sync...")
    sync_device_access()

    while True:
        now = datetime.now()
        if now.hour == SYNC_HOUR and now.minute == 0:
            print("Midnight sync starting...")
            sync_device_access()
            time.sleep(61)  # prevent double-trigger within same minute
        time.sleep(30)

def main():
    sync_thread = threading.Thread(target=sync_scheduler, daemon=True)
    sync_thread.start()

    # ... rest of bridge.py unchanged

What the Member Experiences

Member with expired subscription scans finger:
  → Device shows red ✗ screen
  → "Unregistered ID" or "Access Denied"  
  → Door relay does NOT fire
  → Gate stays closed

Member renews subscription in Rails:
  → Next midnight sync runs
  → Rails returns "ALLOW" for this member
  → Sync finds stored templates in DB
  → Templates re-uploaded to device
  → Next scan: green ✓, door opens

The gate control is entirely device-side. Even if the laptop is off, the internet is down, or the Rails app is unreachable — if a template was deleted, the door stays closed. The device enforces access independently.

Part 4: Fingerprint Enrollment from the Web UI

The original system required three separate manual steps to enroll a new member's fingerprint:

Add the member in the web app
Go to the biometric device, navigate the menu, register their finger manually
Note the device-assigned user ID, come back to the computer, manually insert a row into trn_member_biometric_mappings

Step 3 was where it always broke. Staff would forget the device ID. They'd write it on a scrap of paper and lose it. The mapping table would get out of sync.

The fix: a local Flask API running on the gym laptop alongside bridge.py. The web app's member profile page sends an HTTP request to localhost:5000/enroll, which creates the device user and triggers the enrollment screen — all from a single button click.

Why localhost?

The enrollment API only needs to be reachable from the gym laptop, because enrollment always happens in person at the gym. The browser making the request and the Flask server are on the same machine. No ngrok, no tunnels, no external exposure.

# enroll_api.py

from flask import Flask, request, jsonify
from flask_cors import CORS
from zk import ZK
from zk.user import User
import requests as req
from config import *

app = Flask(__name__)
CORS(app)

RAILS_API_BASE = "https://spine-fitness.com"
DEVICE_SN      = "NFZ8253402448"


def get_next_uid_and_user_id(conn):
    users = conn.get_users()
    if not users:
        return 1, '1'
    max_uid      = max(u.uid for u in users)
    existing_ids = [int(u.user_id) for u in users if str(u.user_id).isdigit()]
    max_user_id  = max(existing_ids) if existing_ids else 0
    return max_uid + 1, str(max_user_id + 1)


@app.route('/health', methods=['GET'])
def health():
    return jsonify({'status': True, 'message': 'Enrollment API running'})


@app.route('/enroll', methods=['POST'])
def enroll():
    data        = request.json
    member_id   = data.get('member_id')
    member_name = data.get('member_name', 'Member')
    compcode    = data.get('compcode', 'SF')

    zk = ZK(DEVICE_IP, port=DEVICE_PORT, timeout=DEVICE_TIMEOUT,
            password=0, force_udp=False, ommit_ping=False)

    try:
        conn = zk.connect()
        conn.disable_device()

        new_uid, new_device_user_id = get_next_uid_and_user_id(conn)

        # Create user record on device (no finger template yet)
        user_obj = User(
            uid=new_uid,
            name=member_name[:24],
            privilege=0,
            password='',
            group_id='',
            user_id=new_device_user_id,
            card=0
        )
        conn.save_user_template(user=user_obj, fingers=[])

        # Trigger fingerprint enrollment screen on device
        conn.enable_device()
        conn.enroll_user(uid=new_uid, temp_id=0)

        # Save mapping to Rails
        req.post(
            f"{RAILS_API_BASE}/api/biometric_mappings",
            json={
                'compcode':       compcode,
                'member_id':      str(member_id),
                'device_user_id': new_device_user_id,
                'device_sn':      DEVICE_SN,
                'uid':            new_uid
            },
            timeout=30
        )

        return jsonify({
            'status':         True,
            'message':        f'Device ready — ask {member_name} to scan finger now!',
            'device_user_id': new_device_user_id
        })

    except Exception as e:
        return jsonify({'status': False, 'message': str(e)}), 500
    finally:
        try:
            conn.enable_device()
            conn.disconnect()
        except:
            pass


if __name__ == '__main__':
    app.run(host='127.0.0.1', port=5000, debug=False)

The UI: Fingerprint Section on Member Profile

The member edit page now has a biometric section that shows the current enrollment status and relevant actions:

<%# In member_list/add_member.html.erb %>

<% if @member && @member.id %>
  <% mapping = TrnMemberBiometricMapping.find_by(
       mbm_compcode: session[:loggedUserCompCode],
       mbm_member_id: @member.id.to_s,
       mbm_is_active: 'Y'
     ) %>

  <div class="form-group row" style="margin-top: 20px;">
    <div class="col-md-12">
      <div class="card" style="padding: 15px;">
        <h5>Biometric Fingerprint</h5>

        <% if mapping %>
          <p>
            <span class="badge badge-success">✓ Enrolled</span>
            Device User ID: <strong><%= mapping.mbm_device_user_id %></strong>
          </p>
          <button type="button"
            onclick="enrollFinger(<%= @member.id %>, '<%= @member.mmbr_name %>')"
            class="btn btn-warning btn-sm">
            Re-enroll Finger
          </button>
          <button type="button"
            onclick="removeMapping(<%= mapping.id %>)"
            class="btn btn-danger btn-sm">
            Remove Mapping
          </button>
        <% else %>
          <p class="text-muted">No fingerprint enrolled.</p>
          <button type="button"
            onclick="enrollFinger(<%= @member.id %>, '<%= @member.mmbr_name %>')"
            class="btn btn-primary btn-sm">
            👆 Enroll Fingerprint
          </button>

          <%# Manual mapping for members already on device %>
          <div style="margin-top: 10px;">
            <input type="text" id="manual_device_uid"
              class="form-control form-control-sm"
              placeholder="Device User ID (manual)" style="width: 200px; display: inline;"/>
            <button type="button"
              onclick="saveManualMapping(<%= @member.id %>, '<%= @member.mmbr_name %>')"
              class="btn btn-secondary btn-sm">
              Save Manual Mapping
            </button>
          </div>
        <% end %>

        <div id="enroll-status" class="mt-2"></div>
      </div>
    </div>
  </div>
<% end %>

function enrollFinger(memberId, memberName) {
  $("#enroll-status").html('<span class="text-info">⏳ Checking enrollment service...</span>');

  // First ping localhost to confirm we're on the gym laptop
  $.ajax({
    url: 'http://localhost:5000/health',
    type: 'GET',
    timeout: 3000,
    success: function() {
      doEnroll(memberId, memberName);
    },
    error: function() {
      $("#enroll-status").html(
        '<span class="text-warning">⚠ Enrollment only works from the gym laptop.</span>'
      );
    }
  });
}

function doEnroll(memberId, memberName) {
  $.ajax({
    url: 'http://localhost:5000/enroll',
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({ member_id: memberId, member_name: memberName, compcode: 'SF' }),
    timeout: 30000,
    success: function(resp) {
      if (resp.status) {
        $("#enroll-status").html('<span class="text-success">✓ ' + resp.message + '</span>');
        setTimeout(function(){ location.reload(); }, 4000);
      } else {
        $("#enroll-status").html('<span class="text-danger">Error: ' + resp.message + '</span>');
      }
    }
  });
}

The health check before enrollment is important — it gives a clear message when someone tries to enroll from home rather than a confusing network error.

Part 5: The Android Backup Bridge

The gym's spare Android phone was already on 24/7 (used for YouTube/music). I put it to work as a backup bridge using Termux.

# Termux setup
pkg update && pkg upgrade -y
pkg install python -y
pip install pyzk requests   # note: pyzk, NOT zk

# Create startup script (runs on phone boot via Termux:Boot)
mkdir -p ~/.termux/boot
cat > ~/.termux/boot/start-bridge.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/sh
termux-wake-lock
cd /data/data/com.termux/files/home
python3 bridge.py &
EOF
chmod +x ~/.termux/boot/start-bridge.sh

The key insight: pip install zk installs Zipkin (a distributed tracing library). The correct package is pip install pyzk. Easy mistake to make, hard to debug if you don't know to look for it.

The termux-wake-lock command prevents Android from killing Termux when it's backgrounded — critical for a bridge that needs to run continuously while YouTube plays in the foreground.

Set battery optimization to "Unrestricted" for Termux in Android Settings to prevent aggressive power management from terminating the process.

Dual Bridge Architecture

With both bridges running:

Phone on  + Laptop off → attendance works via phone ✓
Phone off + Laptop on  → attendance works via laptop ✓
Both on               → both send, Rails deduplication ignores duplicates ✓

The Rails duplicate check (same member + same minute) means double-sends are silently ignored. Running two bridges simultaneously is safe.

Part 6: The ADMS Investigation (And Why I Abandoned It)

I spent significant time trying to make ADMS (the device's built-in cloud push protocol) work. ADMS would have eliminated the need for the Python bridge entirely — the device would push attendance directly to Rails.

The investigation revealed the exact failure chain:

DNS resolution worked — after changing the device's DNS from the router (192.168.31.1) to Google's (8.8.8.8), the device could resolve spine-fitness.com
Port 80 was reachable — curl http://spine-fitness.com/iclock/getrequest from the same network returned OK
Cloudflare activated successfully — Flexible SSL mode set, domain proxied through Cloudflare
Rails ADMS controller was deployed — routes for /iclock/cdata and /iclock/getrequest were live and returning OK
The device still never connected — zero /iclock/ requests appeared in Render logs even after DNS fix and reboot

The most likely root cause: the router has per-device firewall rules blocking outbound HTTP from IoT/embedded devices (MAC address filtering or device category classification). The laptop and phone on the same WiFi could reach the internet fine; the ZK device could not — despite identical network configuration.

The ADMS controller code remains in the codebase for future use if the router configuration ever changes:

# app/controllers/api/adms_controller.rb
class Api::AdmsController < ApplicationController
  skip_before_action :verify_authenticity_token

  def getrequest
    render plain: "OK"
  end

  def handshake
    render plain: "OK"
  end

  def receive
    body = request.body.read
    Rails.logger.info "ADMS received: #{body}"

    sn_match  = body.match(/SN=([^\s&\r\n]+)/i)
    device_sn = sn_match ? sn_match[1] : 'NFZ8253402448'

    body.each_line do |line|
      line = line.strip
      next if line.empty?
      next if line.start_with?("ATTLOG")
      next unless line.split("\t")[0].to_s.match?(/\A\d+\z/)

      parts          = line.split("\t")
      device_user_id = parts[0].to_s.strip
      timestamp      = parts[1].to_s.strip
      punch_time     = Time.zone.parse(timestamp) rescue nil

      next unless punch_time
      next if punch_time.to_date < Date.today

      process_attendance(device_user_id, punch_time, device_sn)
    end

    render plain: "OK"
  end

  private

  def process_attendance(device_user_id, punch_time, device_sn)
    # same logic as BiometricAttendancesController
  end
end

If you're starting fresh and your router doesn't filter IoT devices, ADMS is the cleaner solution — no bridge needed at all.

The Updated Architecture

                    ┌─────────────────────────────┐
                    │   ZK Fingerprint Device      │
                    │   192.168.31.151:4370        │
                    │   Door relay connected        │
                    └──────────┬──────────────────┘
                               │ pyzk TCP
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                │
 ┌────────────────┐  ┌──────────────────┐       │
 │  Python Bridge │  │  Enroll API      │       │
 │  bridge.py     │  │  enroll_api.py   │       │
 │  (gym laptop)  │  │  Flask :5000     │       │
 │                │  │  (gym laptop)    │       │
 │  + sync_access │  └────────┬─────────┘       │
 │    thread      │           │ localhost POST   │
 └───────┬────────┘           │                 │
         │                    │                 │
         │ HTTPS POST         │                 │
         ▼                    ▼                 │
 ┌───────────────────────────────────────────┐  │
 │        Cloudflare (Flexible SSL)          │  │
 └───────────────────┬───────────────────────┘  │
                     │ HTTPS                     │
                     ▼                           │
 ┌───────────────────────────────────────────┐  │
 │     Ruby on Rails (Render)                │  │
 │                                           │  │
 │  POST /api/biometric_attendances          │  │
 │  POST /api/biometric_mappings             │  │
 │  POST /api/biometric_mappings/save_template│  │
 │  GET  /api/access_status                  │  │
 └───────────────────┬───────────────────────┘  │
                     │                           │
                     ▼                           │
 ┌───────────────────────────────────────────┐  │
 │     MySQL (CleverCloud)                   │  │
 │                                           │  │
 │  trn_member_attendances                   │  │
 │  trn_member_biometric_mappings            │  │
 │    + mbm_finger_template (LONGTEXT)       │  │
 │    + mbm_uid (INT)                        │  │
 │  trn_member_subscriptions                 │  │
 └───────────────────────────────────────────┘  │
                                                 │
 ┌───────────────────────────────────────────┐  │
 │  Android Phone (Termux backup bridge)     │──┘
 │  Same WiFi, same device, different host   │
 └───────────────────────────────────────────┘

Key Engineering Decisions in Retrospect

1. Delete the template, not just a flag.
The first instinct is to add an is_blocked flag somewhere and check it in a middleware layer. But that still involves a network call at scan time — and the network can be down. Deleting the template makes the device itself the enforcement layer. No network, no middleware, no latency. The device just can't match a finger that isn't there.

2. Store templates before deletion.
This is the part that's easy to skip and catastrophic if you do. Always save the template bytes to the database before calling conn.delete_user(). The sync script saves first, deletes second — if the save fails, the delete doesn't happen.

3. Never touch admin accounts (privilege=14).
The sync script explicitly skips any user with privilege == 14. These are device admins — staff, trainers, the owner. They should always have access regardless of subscription status. One unguarded delete_user on an admin account during a sync run would be a very bad day.

4. The enrollment API health check.
Before sending the enroll command, the browser pings localhost:5000/health. If it doesn't respond, the user sees "Enrollment only works from the gym laptop" instead of a generic network error. Small UX detail, but it prevents a lot of confused support calls.

5. Render cold starts are real.
The sync script pings the Rails root URL before the actual access_status request. Render's free tier sleeps after inactivity. Without the warmup ping, the first real request would time out, the sync would abort, and nobody would get blocked or restored. The warmup adds ~2 seconds but makes the sync reliable.

Current State

The system has been running in production for several months. The gym has:

Zero attendance records missed due to bridge downtime (dual bridge coverage)
Members with expired subscriptions physically blocked at the door
New member enrollment taking under 30 seconds from web form to working fingerprint
The gym owner checking the live attendance dashboard from home on their phone

The notebook is in a drawer somewhere. Nobody's opened it.

🔗 Live: spine-fitness.com
💻 Source: github.com/imlakshay08/spine-fitness-gym-management-system

If you've dealt with biometric hardware integration or the ZK device ecosystem — I'd love to compare notes in the comments.

How I Built a Rails App That Syncs Empire Flippers Listings to HubSpot and Google Sheets

Lakshay Tyagi — Mon, 25 May 2026 01:32:57 +0000

A Rails integration app that syncs Empire Flippers listings to HubSpot and Google Sheets using Sidekiq, PostgreSQL, and service objects.

The Origin Story

This project started as a coding challenge for a job interview at Empire Flippers — the #1 marketplace for buying and selling online businesses. The challenge was simple on paper:

"Use our Public Listings API as an input data source, store listings in a database, create Deal objects in HubSpot, and run the sync once per day."

What followed was five days of learning Ruby on Rails from scratch, debugging SSL certificates on Windows, fighting libcurl DLLs, pagination loops that ran forever, and ultimately shipping a working integration with 213 real HubSpot deals and a live Google Sheet — all with a full RSpec test suite.

This is that story.

What the App Does

Empire Flippers lists online businesses for sale — Amazon FBA stores, SaaS products, content sites, eCommerce businesses. Their platform is essentially a marketplace for digital assets, similar to a real estate agency but for online businesses.

The challenge was to build a Rails app that:

Fetches all "For Sale" listings from Empire Flippers' public API
Stores listing data in a PostgreSQL database
Creates a corresponding Deal in HubSpot CRM for each listing
Exports all listings to a Google Sheet
Runs the entire sync automatically once per day via background jobs
Never creates duplicate listings or duplicate HubSpot deals — even if the sync runs multiple times

SyncListingsJob (runs daily at midnight via Sidekiq + sidekiq-scheduler)
    ↓
ListingSyncService (orchestrator)
    ├── EmpireFlippersService  →  fetches all listings from EF API (paginated)
    ├── HubspotService         →  creates deals in HubSpot CRM
    └── GoogleSheetsService    →  exports listings to Google Sheet

The Tech Stack

Layer	Technology
Framework	Ruby on Rails 7.1
Database	PostgreSQL
Background Jobs	Sidekiq + sidekiq-scheduler
EF API Client	HTTParty
HubSpot	hubspot-api-client gem
Google Sheets	google-apis-sheets_v4 gem
Testing	RSpec + factory_bot
Environment	dotenv-rails

Architecture: Service Objects

The first design decision was choosing service objects over fat controllers or fat models.

Each service has exactly one responsibility:

# EmpireFlippersService — knows how to talk to the EF API
# HubspotService        — knows how to talk to HubSpot
# GoogleSheetsService   — knows how to talk to Google Sheets
# ListingSyncService    — orchestrates all three, touches nothing else

This matters more than it seems. When the EF API added pagination requirements mid-project, only EmpireFlippersService needed to change. When HubSpot needed a different property format, only HubspotService changed. Nothing else was touched.

This is the Single Responsibility Principle in practice — each class has exactly one reason to change.

The Database Layer: Preventing Duplicates

The Listing model is simple but has two layers of duplicate prevention:

class Listing < ApplicationRecord
  validates :listing_number, presence: true, uniqueness: true
  validates :listing_price, presence: true
end

And at the database level:

add_index :listings, :listing_number, unique: true

Why both? The model validation catches duplicates in Ruby before touching the database. The database index is the last line of defense — even if two requests arrive simultaneously, PostgreSQL rejects the second one.

The database columns:

listing_number              — EF's unique ID for each business
listing_price               — sale price in USD
summary                     — full business description
listing_status              — "For Sale"
hubspot_deal_id             — stored after creating the HubSpot deal
average_monthly_net_profit  — monthly earnings

Fetching Listings: The Pagination Problem

The first version of EmpireFlippersService was simple:

def self.fetch_listings
  response = HTTParty.get(BASE_URL, query: {
    listing_status: "For Sale",
    limit: 100
  })
  response["data"]["listings"]
end

This returned 100 listings. During the interview, the interviewer noted: "There are 213 listings — I want all of them."

The fix required pagination:

def self.fetch_listings
  listings = []
  page = 1

  loop do
    response = HTTParty.get(BASE_URL, query: {
      listing_status: "For Sale",
      limit: 100,
      page: page
    })

    raise "Empire Flippers API error: #{response.code}" unless response.success?

    page_listings = response["data"]["listings"]
    break if page_listings.empty?

    listings.concat(page_listings)
    page += 1
  end

  listings
rescue StandardError => e
  Rails.logger.error "Failed to fetch EF listings: #{e.message}"
  raise
end

How it works: Page 1 returns 100 listings, page 2 returns 100 more, page 3 returns 13, page 4 returns empty — loop breaks. Total: 213.

The raise at the end of the rescue is intentional. Re-raising the error tells Sidekiq the job failed, triggering automatic retries. If the EF API is temporarily down, Sidekiq retries up to 25 times with exponential backoff — no manual intervention required.

The Sync Orchestrator: Idempotent by Design

The ListingSyncService is the heart of the app:

class ListingSyncService
  def self.sync
    listings = EmpireFlippersService.fetch_listings

    listings.each do |listing_data|
      listing = Listing.find_or_create_by(listing_number: listing_data["listing_number"]) do |l|
        l.listing_price = listing_data["listing_price"]
        l.summary = listing_data["summary"]
        l.listing_status = listing_data["listing_status"]
        l.average_monthly_net_profit = listing_data["average_monthly_net_profit"]
      end

      if listing.hubspot_deal_id.nil?
        deal_id = HubspotService.create_deal(listing)
        listing.update(hubspot_deal_id: deal_id)
      end
    end

    GoogleSheetsService.export(Listing.all)
  end
end

Three things worth noting:

find_or_create_by — This is the duplicate prevention for the database. If listing #91258 already exists, return it. If not, create it. The do |l| block only runs for new records.

if listing.hubspot_deal_id.nil? — After saving to the database, check if we already created a HubSpot deal. If yes, skip. If no, create and save the returned deal ID. This prevents duplicate HubSpot deals even if the sync runs ten times.

GoogleSheetsService.export(Listing.all) — We pass all listings from the database, not just new ones. The challenge requires clearing and rewriting the sheet completely each run.

This makes the entire sync idempotent — running it 10 times produces the same result as running it once.

HubSpot Integration: The libcurl Adventure

The HubSpot service itself is straightforward:

class HubspotService
  def self.create_deal(listing)
    client = Hubspot::Client.new(access_token: ENV['HUBSPOT_ACCESS_TOKEN'])

    properties = {
      dealname: "Listing ##{listing.listing_number}",
      amount: listing.listing_price.to_s,
      closedate: (Time.now + 30.days).strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
      description: listing.summary,
      average_monthly_net_profit: listing.average_monthly_net_profit
    }

    response = client.crm.deals.basic_api.create(
      simple_public_object_input_for_create: { properties: properties }
    )

    response.id
  end
end

But getting here on Windows was not straightforward.

The HubSpot gem uses typhoeus internally, which requires libcurl. On Windows, typhoeus looks for libcurl.dll specifically — not the curl executable that ships with Windows 10+.

The fix:

# Download the curl DLL
Invoke-WebRequest -Uri "https://curl.se/windows/dl-8.11.1_2/curl-8.11.1_2-win64-mingw.zip" -OutFile "$env:TEMP\curl.zip"
Expand-Archive "$env:TEMP\curl.zip" -DestinationPath "$env:TEMP\curl"

# Copy to Ruby's bin directory
Copy-Item "$env:TEMP\curl\curl-8.11.1_2-win64-mingw\bin\libcurl-x64.dll" "C:\Ruby31-x64\bin\"

# Create a copy with the exact name typhoeus looks for
Copy-Item "C:\Ruby31-x64\bin\libcurl-x64.dll" "C:\Ruby31-x64\bin\libcurl.dll"

Then SSL verification on Windows required one more fix — a Typhoeus initializer:

# config/initializers/hubspot.rb
require 'typhoeus'

Typhoeus.before do |request|
  request.options[:ssl_verifypeer] = false
  request.options[:ssl_verifyhost] = 0
end

This is a Windows-only workaround. On a Linux production server, neither fix is needed.

Google Sheets Integration: The Permission Problem

The Google Sheets service authenticates via a service account:

def client
  @client ||= begin
    service = Google::Apis::SheetsV4::SheetsService.new
    service.authorization = Google::Auth::ServiceAccountCredentials.make_creds(
      json_key_io: File.open(ENV['GOOGLE_SHEETS_CREDENTIALS_PATH']),
      scope: SCOPE
    )
    service
  end
end

The @client ||= is memoization — create the authenticated client once per object instance, reuse it for all API calls. No re-authenticating on every sheet operation.

The first attempt to create a sheet from the service account returned a 403 PERMISSION_DENIED. The reason: service accounts live in their own Google Drive, separate from your personal Drive. They can't create sheets in your Drive without being explicitly granted access.

The clean solution: create the sheet manually in Google Sheets, share it with the service account email (empire-sync@project-id.iam.gserviceaccount.com), and store the sheet ID in .env. The service account then has Editor access to write data.

def find_or_create_sheet
  sheet_id = GoogleSheetReference.first&.sheet_id

  if sheet_id.nil?
    sheet_id = ENV['GOOGLE_SHEET_ID']
    GoogleSheetReference.create!(sheet_id: sheet_id)
  end

  sheet_id
end

GoogleSheetReference stores the sheet ID in the database — the sheet is created once and reused on every subsequent sync run.

Writing the data:

def write_rows(sheet_id, listings)
  values = [["Listing #", "Listing Price", "Summary"]]

  listings.each do |listing|
    values << [
      listing.listing_number.to_s,
      listing.listing_price.to_s,
      listing.summary
    ]
  end

  value_range = Google::Apis::SheetsV4::ValueRange.new(values: values)

  client.update_spreadsheet_value(
    sheet_id,
    'Sheet1',
    value_range,
    value_input_option: 'RAW'
  )
end

Each run: clear the sheet, write the header row, write one row per listing. Simple and deterministic.

Testing with RSpec: TDD in Practice

Every service has a corresponding spec. The testing philosophy: never hit real APIs in tests. Stub everything external, test your logic in isolation.

RSpec.describe ListingSyncService do
  describe ".sync" do
    let(:fake_listings) do
      [{
        "listing_number" => 12345,
        "listing_price" => 50000,
        "summary" => "A great business",
        "listing_status" => "For Sale"
      }]
    end

    before do
      allow(EmpireFlippersService).to receive(:fetch_listings).and_return(fake_listings)
      allow(HubspotService).to receive(:create_deal).and_return("hs_deal_123")
      allow(GoogleSheetsService).to receive(:export)
    end

    it "syncs listings from Empire Flippers" do
      ListingSyncService.sync
      expect(Listing.count).to eq(1)
      expect(Listing.first.listing_number).to eq(12345)
    end

    it "does not create duplicate listings" do
      ListingSyncService.sync
      ListingSyncService.sync
      expect(Listing.count).to eq(1)
    end

    it "creates a hubspot deal for new listings" do
      ListingSyncService.sync
      expect(HubspotService).to have_received(:create_deal)
      expect(Listing.first.hubspot_deal_id).to eq("hs_deal_123")
    end

    it "does not create hubspot deal if one already exists" do
      ListingSyncService.sync
      allow(HubspotService).to receive(:create_deal)
      ListingSyncService.sync
      expect(HubspotService).to have_received(:create_deal).once
    end
  end
end

The allow(...).to receive(...).and_return(...) pattern is stubbing — replacing the real method with a fake that returns predetermined data. Tests run in milliseconds and never depend on the internet.

The duplicate prevention test is particularly important: run the sync twice, expect only one listing in the database. If find_or_create_by is broken, this test catches it immediately.

The Daily Scheduler

Sidekiq handles background job processing. sidekiq-scheduler adds cron-like scheduling on top:

# config/sidekiq.yml
:scheduler:
  :schedule:
    sync_listings:
      :cron: "0 0 * * *"
      :class: SyncListingsJob

0 0 * * * = minute 0, hour 0, every day = midnight.

The job itself is intentionally thin:

class SyncListingsJob < ApplicationJob
  queue_as :default

  def perform
    ListingSyncService.sync
  end
end

Business logic lives in the service. The job is just a trigger. This makes the service independently testable and independently callable — from the console, from a rake task, from anywhere.

End-to-End Results

After running ListingSyncService.sync in the Rails console:

Listing.count                                    # => 213
Listing.where.not(hubspot_deal_id: nil).count    # => 213

213 listings saved to PostgreSQL. 213 HubSpot deals created with names like "Listing #91258", amounts like $1,293,233, and 30-day close dates. 213 rows in the Google Sheet with headers.

Running the sync a second time:

Listing.count                                    # => 213  (no duplicates)
HubSpot deals created                            # => 0    (all already exist)

Idempotency confirmed.

Key Learnings

1. Service objects make testing trivial. When each service has one job, you stub one thing and test one thing. The alternative — fat models or fat controllers — makes tests brittle and slow.

2. Idempotency is a design decision, not an afterthought. find_or_create_by + hubspot_deal_id nil check = a sync that can run 100 times safely. Design for repeated execution from the start.

3. Windows is a special case. Most Rails documentation assumes Linux. libcurl, SSL certificates, PowerShell aliases — none of these bite you on a Linux server. If you're developing on Windows, budget time for platform-specific debugging.

4. Memoize expensive operations. The @client ||= pattern in GoogleSheetsService creates one authenticated connection per sync run. Without it, every API call would re-authenticate — unnecessary and slower.

5. Re-raise errors in background jobs. Catching an error and logging it silently means Sidekiq thinks the job succeeded. Re-raising means Sidekiq retries automatically. For production background jobs, retries are almost always what you want.

What I'd Add Next

Pagination for listings over 1000 — loop until empty works but could be parallelized with ProcessListingJob workers for scale
Sentry for error alerting — know within minutes when a midnight sync fails
Webhook from EF — instead of polling once per day, react to listing changes in real time
Soft deletes for sold listings — currently sold listings stay in the database indefinitely; they should be marked and excluded from HubSpot

The Bigger Picture

Empire Flippers facilitates the sale of online businesses in the 5 to 8 figure USD range. Every listing in that Google Sheet and every deal in that HubSpot account represents a real business someone built — an Amazon FBA store, a content site, a SaaS product — and is now ready to sell.

Building integrations between systems is what Rails is genuinely good at. Not flashy frontends or complex algorithms — clean, maintainable code that connects APIs together and runs reliably in the background while you sleep.

That's what this project is.

💻 Source Code: github.com/imlakshay08/empire-sync

If you've built HubSpot or Google Sheets integrations with Rails and ran into different issues — I'd love to hear about it in the comments.

Connecting a Biometric Fingerprint Device to a Rails Web App Using Python — A Complete Walkthrough

Lakshay Tyagi — Thu, 07 May 2026 09:40:42 +0000

👋 Introduction

When I was building a gym management system for a real gym in New Delhi, one of the most interesting challenges was connecting a physical biometric fingerprint device to my cloud-hosted Ruby on Rails app.

The gym wanted to:

✅ Track member attendance via fingerprint scanning
✅ Automatically deny access to members with expired subscriptions
✅ Prevent duplicate check-ins
✅ See attendance on the admin dashboard in real-time

The catch? The biometric device only speaks to the local network. My Rails app is hosted on Render (cloud). They can't talk to each other directly.

The solution? A Python bridge script running on the gym's laptop that reads fingerprint punches from the device and forwards them to the Rails API via HTTP.

This post covers the entire pipeline — Python bridge → Rails API → Database — with real code from production.

🏗️ Architecture: The Full Pipeline

┌─────────────────────┐
│  ZK Fingerprint      │
│  Biometric Device    │
│  (192.168.1.201)     │
└──────────┬──────────┘
           │ pyzk SDK (TCP)
           ▼
┌──────────────────────────┐
│  Python Bridge Script    │
│  (bridge.py)             │
│  Runs on gym laptop      │
│  Polls every 20 seconds  │
│  Deduplicates locally    │
└──────────┬───────────────┘
           │ HTTP POST (JSON)
           ▼
┌──────────────────────────────────────┐
│  Ruby on Rails API (Render cloud)    │
│  POST /api/biometric_attendances     │
│                                      │
│  1. Find biometric mapping           │
│  2. Check for duplicate punches      │
│  3. Validate subscription            │
│  4. Store attendance                 │
│  5. Return ALLOWED / DENIED          │
└──────────┬───────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│  MySQL Database (CleverCloud)        │
│                                      │
│  trn_member_biometric_mappings       │
│  trn_member_attendances              │
│  trn_member_subscriptions            │
└──────────────────────────────────────┘

Three components, two languages, one seamless flow.

🐍 Part 1: The Python Bridge (Gym Laptop Side)

The Problem

The biometric device (a ZK-based fingerprint scanner) is on the gym's local network at 192.168.1.201. It stores fingerprints and punch records internally. It has no concept of "calling a web API."

My Rails app is hosted on Render — a cloud server that the device can't reach directly.

Solution: A Python script that acts as the middleman — reads from the device using the pyzk SDK, and forwards punches to Rails via HTTP.

Configuration

# biometric_bridge/config.py

DEVICE_IP = "192.168.1.201"
DEVICE_PORT = 4370
DEVICE_TIMEOUT = 5

RAILS_API_URL = "https://spine-fitness.com/api/biometric_attendances"
COMP_CODE = "SF"

POLL_INTERVAL_SECONDS = 20

Key decisions:

Port 4370 — Standard ZK biometric device communication port
20-second polling — Balances real-time feel vs. not overwhelming the device
Company code "SF" — Supports multi-tenant architecture (future-proof for multiple gyms)

The Bridge Script

# biometric_bridge/bridge.py

from zk import ZK
import requests
import time
from datetime import datetime
from config import *

def send_to_rails(payload):
    try:
        response = requests.post(
            RAILS_API_URL,
            json=payload,
            timeout=5
        )
        print(f"Sent: {payload} | Response: {response.status_code}")
    except Exception as e:
        print("Rails API error:", e)

def main():
    zk = ZK(
        DEVICE_IP,
        port=DEVICE_PORT,
        timeout=DEVICE_TIMEOUT,
        password=0,
        force_udp=False,
        ommit_ping=False
    )

    print("Connecting to biometric device...")

    try:
        conn = zk.connect()
        conn.disable_device()

        print("Connected to device")
        print("Fetching attendance logs...")

        last_sent = set()

        while True:
            attendances = conn.get_attendance()

            for att in attendances:
                key = f"{att.user_id}-{att.timestamp}"

                # Prevent duplicate sending
                if key in last_sent:
                    continue

                payload = {
                    "compcode": COMP_CODE,
                    "user_id": att.user_id,
                    "timestamp": att.timestamp.strftime("%Y-%m-%d %H:%M:%S"),
                    "device_sn": conn.serial_number
                }

                send_to_rails(payload)
                last_sent.add(key)

            time.sleep(POLL_INTERVAL_SECONDS)

    except Exception as e:
        print("Device connection error:", e)

    finally:
        try:
            conn.enable_device()
            conn.disconnect()
        except:
            pass

if __name__ == "__main__":
    main()

How It Works Step by Step

1. Connect to the device

zk = ZK(DEVICE_IP, port=DEVICE_PORT, timeout=DEVICE_TIMEOUT, ...)
conn = zk.connect()
conn.disable_device()  # Prevents new operations while reading

The pyzk library connects to the ZK device via TCP on port 4370. We temporarily disable the device during reads to prevent data corruption.

2. Poll every 20 seconds

while True:
    attendances = conn.get_attendance()
    # ... process ...
    time.sleep(POLL_INTERVAL_SECONDS)

The script runs in an infinite loop, fetching all attendance records from the device. The device stores punches internally, so we get the full history each time.

3. Deduplicate locally

last_sent = set()

key = f"{att.user_id}-{att.timestamp}"
if key in last_sent:
    continue

Since get_attendance() returns all historical records, we use an in-memory set to track what's already been sent. Only new punches get forwarded. This is deduplication layer 1 — the Rails API has its own deduplication as layer 2.

4. Forward to Rails API

payload = {
    "compcode": COMP_CODE,
    "user_id": att.user_id,
    "timestamp": att.timestamp.strftime("%Y-%m-%d %H:%M:%S"),
    "device_sn": conn.serial_number
}
send_to_rails(payload)

Each punch becomes a clean JSON payload with all the context Rails needs.

Auto-Start on Windows

The gym staff shouldn't need to "start the bridge" manually. A .bat file handles this:

:: biometric_bridge/start_biometric.bat
cd C:\biometric_bridge
python bridge.py

This can be placed in the Windows Startup folder so the bridge starts automatically when the gym opens and the laptop powers on.

Dependencies

# biometric_bridge/requirements.txt
pyzk
requests

Just two dependencies — pyzk for ZK device communication and requests for HTTP calls. Minimal and reliable.

💎 Part 2: The Rails API (Cloud Server Side)

The Route

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    resources :biometric_attendances, only: [:create]
  end
end

This gives us: POST /api/biometric_attendances

The Controller

When the Python bridge sends a punch, the Rails API processes it through a 4-step pipeline:

# app/controllers/api/biometric_attendances_controller.rb

class Api::BiometricAttendancesController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    compcode       = params[:compcode].to_s
    device_user_id = params[:user_id].to_i
    device_sn      = params[:device_sn].to_s
    punch_time     = Time.zone.parse(params[:timestamp]) rescue Time.current

    # ── STEP 1: Find biometric mapping ──
    mapping = TrnMemberBiometricMapping.active.find_by(
      mbm_compcode:       compcode,
      mbm_device_user_id: device_user_id,
      mbm_device_sn:      device_sn
    )

    unless mapping
      render json: {
        status: false,
        message: "Biometric user not mapped"
      }, status: 404
      return
    end

    member = mapping.member

    # ── STEP 2: Ignore duplicate punches (same member, same minute) ──
    if duplicate_punch?(member.id, punch_time)
      render json: { status: true, message: "Duplicate ignored" }
      return
    end

    # ── STEP 3: Validate subscription ──
    subscription = latest_subscription(member.id, compcode)

    if subscription && subscription.ms_end_date >= Date.today
      att_status = "ALLOWED"
      reason     = nil
    else
      att_status = "DENIED"
      reason     = "Subscription expired"
    end

    # ── STEP 4: Store attendance ──
    TrnMemberAttendance.create!(
      att_compcode:       compcode,
      att_member_id:      member.id,
      att_device_user_id: device_user_id,
      att_device_sn:      device_sn,
      att_punch_time:     punch_time,
      att_punch_date:     punch_time.to_date,
      att_status:         att_status,
      att_reason:         reason
    )

    render json: { status: true, access: att_status }
  end

  private

  def duplicate_punch?(member_id, time)
    TrnMemberAttendance.where(
      att_member_id: member_id,
      att_punch_time: time.beginning_of_minute..time.end_of_minute
    ).exists?
  end

  def latest_subscription(member_id, compcode)
    TrnMemberSubscription
      .where(ms_compcode: compcode, ms_member_id: member_id)
      .order(ms_end_date: :desc)
      .first
  end
end

🛡️ Two Layers of Deduplication

This is important — deduplication happens at both levels:

Layer	Where	How	Why
Layer 1	Python bridge	In-memory `set` of `{user_id}-{timestamp}` keys	Prevents resending the same device record on every poll cycle
Layer 2	Rails API	Database query for same member + same minute	Catches duplicates if the bridge restarts (set resets), or if the device sends duplicate records

Member scans finger
       │
       ▼
Python bridge: "Already in last_sent?" ──YES──▶ Skip
       │ NO
       ▼
Rails API: "Punch in same minute?" ──YES──▶ Return "Duplicate ignored"
       │ NO
       ▼
Store attendance ✅

This double-layer approach means the system is resilient to:

Bridge restarts (set clears → Layer 2 catches it)
Device quirks (some ZK devices record multiple entries per scan)
Network retries (if the bridge retries a failed request)

🗄️ Database Design

The Bridge Table: `trn_member_biometric_mappings`

Column	Type	Purpose
`mbm_compcode`	string	Company code (multi-tenant)
`mbm_device_user_id`	integer	User ID on the biometric device
`mbm_device_sn`	string	Device serial number
`mbm_member_id`	integer	FK → `mst_members_lists.id`
`mbm_status`	string	`ACTIVE` / `INACTIVE`

Why is this needed? The biometric device assigns its own user IDs (1, 2, 3...). These don't match your database. This table says "Device user #42 on device SN-ABC = Member Rahul Sharma (ID: 156)".

The Attendance Table: `trn_member_attendances`

Column	Type	Purpose
`att_member_id`	integer	FK → member
`att_device_user_id`	integer	Device user ID
`att_device_sn`	string	Device serial
`att_punch_time`	datetime	Exact punch time
`att_punch_date`	date	For easy date-based queries
`att_status`	string	`ALLOWED` or `DENIED`
`att_reason`	string	Why denied (if applicable)

Key design decision: Even DENIED attempts are stored. This lets the gym owner see which expired members are still trying to come — useful for renewal follow-ups.

🧪 Testing the Full Pipeline

Test with cURL (bypassing the Python bridge)

# Active member
curl -X POST https://spine-fitness.com/api/biometric_attendances \
  -H "Content-Type: application/json" \
  -d '{
    "compcode": "SF",
    "user_id": 42,
    "device_sn": "CRT5200-SN001",
    "timestamp": "2026-03-12 07:30:00"
  }'
# → {"status":true,"access":"ALLOWED"}

# Expired member
# → {"status":true,"access":"DENIED"}

# Unknown biometric ID
# → {"status":false,"message":"Biometric user not mapped"}

Test the Python bridge locally

cd biometric_bridge
pip install -r requirements.txt
python bridge.py
# → Connecting to biometric device...
# → Connected to device
# → Fetching attendance logs...
# → Sent: {...} | Response: 200

🧩 Edge Cases I Solved

Edge Case	Solution
Device returns ALL historical records every poll	Python-side `last_sent` set filters to only new records
Member scans finger 3 times rapidly	Rails-side 1-minute deduplication window
Bridge script crashes / laptop restarts	`.bat` file in Startup folder auto-restarts; Rails Layer 2 catches re-sent duplicates
Gym has multiple devices	`device_sn` is part of the mapping — same user_id on different devices = different members
Timestamp timezone mismatch	`Time.zone.parse` with `rescue Time.current` fallback
Member renews subscription mid-day	`ms_end_date >= Date.today` check means renewal takes effect immediately
Member leaves permanently	Set `mbm_status` to `INACTIVE` — `.active` scope blocks without deleting data
Network/API timeout	Python `requests.post(timeout=5)` with try/except — failed sends are logged, not fatal

📊 How This Powers the Dashboard

All attendance data flows to the admin dashboard in real-time:

🟢 Active members — subscription valid, attendance tracked
🟡 Expiring soon — auto-triggers WhatsApp reminders
🔴 Expired — DENIED attendance logged, visible to gym owner

The gym owner sees a member scan their finger, and within seconds the dashboard reflects it — all without touching a single register.

💡 Key Takeaways

Use a bridge pattern when hardware can't talk to cloud directly. A simple Python script solved the hardware↔cloud gap.
Deduplicate at every layer. Don't trust any single layer to handle it perfectly.
Store denied attempts. They're not failures — they're business intelligence.
Keep the bridge minimal. Two dependencies (pyzk + requests), one config file, one script. Less can go wrong.
Auto-start everything. The gym staff shouldn't need to know Python exists. A .bat file in Startup and it just works.
Multi-language is fine. Python is better at hardware communication (pyzk), Rails is better at web apps. Use the right tool for each layer.

🏁 Conclusion

This feature taught me that production software often lives at the intersection of hardware and software. The biometric device, the Python bridge, the Rails API, and the MySQL database — four different technologies working together to create a seamless experience: member scans finger → attendance appears on dashboard.

The most satisfying moment? Watching the gym owner check the dashboard and see real-time attendance without touching a single notebook.

🔗 Live App: spine-fitness.com
💻 Full Source Code: GitHub
📂 Python Bridge Code: biometric_bridge/

Found this useful? Drop a ❤️! Got questions about biometric integration or the Python bridge? Let's chat in the comments!

How I Ditched Interakt and Built a Direct WhatsApp Automation Pipeline with Meta Cloud API

Lakshay Tyagi — Thu, 07 May 2026 05:30:18 +0000

Originally published on Hashnode

A follow-up to my previous post on building Spine Fitness — a production gym management system used by 200+ members daily.

👉 In this post, I’ll walk through why I replaced Interakt with Meta Cloud API, the issues I faced, and how I built a reliable, production-ready WhatsApp automation pipeline.

The Backstory

A few months ago, I published a post about building Spine Fitness — a full-stack gym management system I deployed for a real gym in Dwarka, New Delhi. The system replaced physical notebooks with a Rails app that handled member management, biometric attendance, payments, and WhatsApp notifications.

In that post, I mentioned using Interakt as the WhatsApp API provider.

I no longer use Interakt.

This is the story of why I switched, the absolute nightmare of dealing with Meta's ecosystem, and how I eventually built a clean, direct integration with Meta Cloud API — from scratch — that now reliably sends automated membership reminders to gym members every morning at 10 AM IST.

What Was Working Before (And What Wasn't)

The Interakt setup seemed fine on paper. I had:

A connected WhatsApp number (8920)
Approved message templates
A Rails service (Interakt::SendWhatsapp) making API calls
A cron job firing daily at 10 AM
A trn_whatsapp_logs table logging every attempt

But when I checked the logs, something was wrong.

Every single message had wl_status = 'QUEUED'. No delivered. No read. Just QUEUED — forever.

SELECT wl_status, COUNT(*) FROM trn_whatsapp_logs GROUP BY wl_status;
-- QUEUED: 13
-- DELIVERED: 0
-- READ: 0

Interakt's dashboard showed messages going out. Single tick on WhatsApp. Members never received anything.

I contacted Interakt support. They said the number would be removed from their system. Weeks passed. It wasn't removed. Meanwhile, messages kept getting queued and silently dropped.

I decided to move on.

The Plan: Go Direct with Meta Cloud API

Instead of relying on a BSP (Business Solution Provider) like Interakt, I'd connect directly to Meta's WhatsApp Cloud API. Same infrastructure the big players use — no middleman, full control.

The plan was simple:

Register 8920 on Meta Cloud API
Create message templates
Replace Interakt::SendWhatsapp with Meta::SendWhatsapp in Rails
Set up a webhook for delivery status updates

Simple in theory. Absolutely chaotic in practice.

Week One: The Meta Setup Maze

Haptik Was Everywhere

When I logged into Meta Business Manager, I found that both my numbers (7011 and 8920) had Haptik (Interakt's parent company) as a partner with full control. Even after Interakt said they removed 8920, Haptik still appeared in the partners tab.

This meant any attempt to register 8920 directly on Meta Cloud API failed with:

"Unsupported post request. Object with ID '1073316579198774' does not exist,
cannot be loaded due to missing permissions..."

The number existed. It just wasn't mine yet.

The Payment Method Loop

After finally getting Interakt to release 8920, I tried adding a payment method to the WhatsApp Business Account. Meta charged my card ₹3 as verification — four separate times — and never actually saved it.

The Developer Console kept screaming "Missing valid payment method" even after the WABA settings clearly showed Visa ****4009 as default. I eventually realized this was a Meta UI bug specific to India accounts. The payment was there. The console just couldn't see it.

The Display Name That Wouldn't Approve

I registered 8920 on Meta Cloud API and submitted "Spine Fitness" as the display name. It went into PENDING_REVIEW.

It stayed there for two days.

Then it came back as DECLINED.

Apparently "Spine Fitness" was too generic. Meta's guidelines require the display name to clearly and uniquely represent your business. I resubmitted as "Spine Fitness Gym Dwarka" — specific enough to pass their guidelines — and it was approved within hours.

The Code Change: Surprisingly Clean

Once the Meta side was sorted, the Rails code change was actually minimal. I created a new service file:

# app/services/meta/send_whatsapp.rb
module Meta
  class SendWhatsapp
    API_URL = "https://graph.facebook.com/v19.0"

    def self.send_template(phone:, template:, body_values:)
      phone = phone.to_s.gsub(/\D/, "").last(10)
      return { http_code: 0, body: {}, raw: "Invalid phone" } unless phone.length == 10

      uri = URI("#{API_URL}/#{ENV['WHATSAPP_PHONE_ID']}/messages")

      payload = {
        messaging_product: "whatsapp",
        to: "91#{phone}",
        type: "template",
        template: {
          name: template,
          language: { code: "en" },
          components: [{
            type: "body",
            parameters: body_values.map { |v| { type: "text", text: v.to_s } }
          }]
        }
      }

      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      request = Net::HTTP::Post.new(uri)
      request["Authorization"] = "Bearer #{ENV['WHATSAPP_TOKEN']}"
      request["Content-Type"] = "application/json"
      request.body = payload.to_json

      response = http.request(request)
      parsed_body = JSON.parse(response.body) rescue {}
      { http_code: response.code.to_i, body: parsed_body, raw: response.body }
    end
  end
end

And changed one line in the job:

# Before
response = Interakt::SendWhatsapp.send_template(...)

# After
response = Meta::SendWhatsapp.send_template(...)

Two environment variables on Render:

WHATSAPP_PHONE_ID=1073316579198774
WHATSAPP_TOKEN=<permanent system user token>

That was it for the sending side.

The Template Problem: Meta Hates "Renew Now"

My original template said:

"Hi {{1}}, your membership at Spine Fitness expires on {{2}}. Renew now to avoid interruption. Contact us or visit the gym."

Meta flagged it as Marketing. Every rewrite got flagged. Anything with "renew", "visit us", or "contact us" triggered the marketing classifier.

The fix was to make it purely transactional — no call to action, no promotional language:

"Your membership at Spine Fitness (ID: {{1}}) will expire on {{2}}. This is an automated notification."

Boring? Yes. Approved as Utility? Also yes. And Utility templates are cheaper and have fewer delivery restrictions than Marketing ones.

The Delivery Problem: App Was Unpublished

After all of this, messages were still only delivering to numbers that had previously messaged 8920 first. My number worked. My mother's worked (after she sent "Hi" to 8920 first). Everyone else got accepted by the API but never actually received the message.

I spent a long time chasing the wrong culprits — display name status, payment method, credit lines, contact book theory. The actual reason was simpler and more embarrassing:

My Meta Developer App was unpublished.

In development mode, WhatsApp API has severe restrictions on who can receive messages. The moment I published the app (which required adding a privacy policy URL, an app icon, and completing app review), messages started going to everyone — no prior interaction required.

That single toggle fixed what two weeks of debugging couldn't.

Adding Webhook Delivery Tracking

With Interakt, I never got real delivery status back. With Meta, I could set up a webhook to receive sent, delivered, and read status updates in real time.

# app/controllers/webhooks/meta_controller.rb
class Webhooks::MetaController < ApplicationController
  skip_before_action :verify_authenticity_token

  def verify
    mode      = params['hub.mode']
    token     = params['hub.verify_token']
    challenge = params['hub.challenge']

    if mode == 'subscribe' && token == ENV['WHATSAPP_WEBHOOK_TOKEN']
      render plain: challenge, status: :ok
    else
      head :forbidden
    end
  end

  def receive
    body = JSON.parse(request.body.read)
    entries = body.dig('entry') || []

    entries.each do |entry|
      entry.dig('changes')&.each do |change|
        change.dig('value', 'statuses')&.each do |status|
          process_status(status)
        end
      end
    end

    head :ok
  rescue => e
    Rails.logger.error "[MetaWebhook] Error: #{e.message}"
    head :ok
  end

  private

  def process_status(status)
    message_id = status['id']
    status_val = status['status']&.upcase
    return unless message_id.present?
    return unless %w[DELIVERED READ FAILED SENT].include?(status_val)

    log = TrnWhatsappLog.find_by(wl_interakt_msg_id: message_id)
    return unless log

    case status_val
    when 'DELIVERED'
      log.update!(wl_status: 'DELIVERED', wl_delivered_at: Time.current)
    when 'READ'
      log.update!(wl_status: 'READ', wl_read_at: Time.current)
    when 'FAILED'
      error = status.dig('errors', 0, 'message') || 'Unknown error'
      log.update!(wl_status: 'FAILED', wl_failed_reason: error)
    end

    Rails.logger.info "[MetaWebhook] Updated log #{log.id} → #{status_val}"
  end
end

One important step that wasn't obvious from the docs — I had to explicitly subscribe my app to the correct WABA via API:

curl -X POST \
  "https://graph.facebook.com/v19.0/1603252984268401/subscribed_apps" \
  -H "Authorization: Bearer YOUR_TOKEN"

Without this, the webhook configuration in the Developer Console subscribes to the test WABA, not your production one. Real delivery events never arrive.

Once subscribed correctly, the logs updated in real time:

[MetaWebhook] Updated log 30 → READ
[MetaWebhook] Updated log 32 → READ

The Final State

Here's what the full pipeline looks like now:

cron-job.org (daily 4:30 UTC / 10:00 AM IST)
    │
    ▼
GET /cron/send_expiry_whatsapp
    │
    ▼
MembershipExpiryWhatsappJob (:expiring / :expired)
    │
    ├── Query members expiring in 3 days (or already expired)
    ├── Skip if already DELIVERED or READ
    ├── Call Meta Cloud API
    ├── Log response to trn_whatsapp_logs (status: QUEUED)
    │
    ▼
Meta WhatsApp Cloud API
    │
    ▼
Member's WhatsApp (message delivered)
    │
    ▼
POST /webhooks/meta (delivery status webhook)
    │
    ▼
trn_whatsapp_logs updated: QUEUED → DELIVERED → READ

And the numbers after going live:

Metric	Interakt	Meta Cloud API
Messages delivered	0	✅ All
Status tracking	❌ Never updated	✅ Real-time
Cost per message	~₹0.30 + BSP fee	₹0.12 (utility)
Cold outreach	❌ Broken	✅ Works
Setup pain	Low	Very high

What I'd Tell Myself Before Starting

1. Go direct from the start. BSPs like Interakt add cost and a dependency. If you're building something custom, Meta Cloud API gives you full control and better pricing.

2. Publish your app early. The development mode restriction is the least documented and most impactful limitation. You'll waste days debugging delivery issues that disappear the moment you go live.

3. Display names matter more than you think. Generic names get declined. Be specific — include your city, your category, something that makes the name uniquely yours.

4. Subscribe your webhook to the right WABA. The Developer Console subscribes to the test WABA by default. Make the API call to subscribe your production WABA explicitly.

5. Use Utility templates, not Marketing. Avoid action words. Make it sound like a system notification. It's cheaper and has fewer delivery restrictions.

What's Next

The automation is live and running daily. Members are receiving expiry reminders automatically. The gym owner stopped making manual phone calls.

Next up: a member-facing view so members can check their own subscription status, and SMS fallback for members not on WhatsApp.

Spine Fitness is live at spine-fitness.com. Source code on GitHub.

If you found this useful — or if you've been through the Meta API maze yourself — drop a comment. I'd love to hear your war stories.

Step-by-step Installation guide for Ruby

Lakshay Tyagi — Sun, 02 Nov 2025 01:49:57 +0000

Installing Ruby on Xubuntu (My Notes from The Odin Project)

Before jumping into Ruby on Rails, we first need to set up Ruby itself.

It sounds simple, but trust me — this step can get messy if you skip details.

I went through this recently while following The Odin Project, and here’s a cleaner, beginner-friendly walkthrough based on my own experience.

Why You Need Ruby First

Rails runs on Ruby, so before creating your first app, you need the correct Ruby version and a version manager to switch between them easily.

I’ll be using rbenv, which helps install and manage Ruby versions safely without touching system files.

Step 1: Update Your System

Always start fresh!

Open your terminal (Ctrl + Alt + T on Xubuntu) and update existing packages:

sudo apt update && sudo apt upgrade

This ensures your system’s libraries are current.
You’ll be asked for your password and to confirm updates — press Y when prompted.

Step 2: Install Required Dependencies

Ruby needs a few libraries and tools to build properly:

sudo apt install gcc make libssl-dev libreadline-dev zlib1g-dev libsqlite3-dev libyaml-dev

💡 Linux Tip:
Ctrl + Shift + C → Copy from terminal
Ctrl + Shift + V → Paste into terminal

Step 3: Install rbenv

rbenv lets you install and switch between Ruby versions easily.

Clone it from GitHub:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Then initialize it:

~/.rbenv/bin/rbenv init

Now close your terminal and reopen it to refresh your environment variables.

Verify installation:

rbenv -v

You should see something like:
rbenv 1.x.x

Step 4: Add ruby-build Plugin

This plugin helps rbenv compile and install Ruby versions.

mkdir -p "$(rbenv root)"/plugins
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Now rbenv can handle Ruby installations.

Step 5: Install Ruby

We’re finally ready! Run:

rbenv install 3.4.2 --verbose

⏳ This might take 10–15 minutes.
The --verbose flag lets you see progress so you know it hasn’t frozen.

If you get an error like:

ruby-build: definition not found: 3.4.2

Update ruby-build and try again:

git -C "$(rbenv root)"/plugins/ruby-build pull

Step 6: Set Default Ruby Version

Once installation completes, set it as your global Ruby version:

rbenv global 3.4.2

Verify with:

ruby -v

If everything worked, you’ll see something like:

ruby 3.4.2pXXX (20XX-XX-XX revision XXXXX) [x86_64-linux]

🎉 Congrats — you’ve officially installed Ruby!

What’s Next

With Ruby set up, you’re ready to install Rails and start building your first app.
You can also watch my video walkthrough of this process here 🎥 — [YouTube Link].

Credits

This post is inspired by The Odin Project’s “Installing Ruby” lesson.
I followed their guidance but rewrote this post based on my own notes and experience using Xubuntu Linux.

DEV Community: Lakshay Tyagi

What 6 Months in Production Taught Me About Biometric Gate Control: Race Conditions, Ghost Fingerprints, and Building a System That Actually Works

The Mental Model Most People Get Wrong

Gate Control Was Never Running

The Sync Blind Spot

Two-Phase Save/Delete — The Safety Guarantee

The Enrollment Race Condition

The Bugs Nobody Talks About

Operational Changes

Why Enterprise Systems Don't Have These Problems

Current State

Key Takeaways

From Polling to Production: How I Upgraded My Biometric Integration with Gate Control, Auto-Enrollment, and 24/7 Reliability

The Problem with "Good Enough"

What I Built (The Upgrade Summary)

Part 1: Fixing the "Today Only" Problem

Part 2: Auto-Start on Windows — The Silent Background Process

Preventing Sleep from Killing the Process

Part 3: The Gate Control Problem — Why DENIED Wasn't Enough

The Database Change

The Sync Script

The Rails API Endpoint

Running Sync Automatically

What the Member Experiences

Part 4: Fingerprint Enrollment from the Web UI

Why localhost?

The UI: Fingerprint Section on Member Profile

Part 5: The Android Backup Bridge

Dual Bridge Architecture

Part 6: The ADMS Investigation (And Why I Abandoned It)

The Updated Architecture

Key Engineering Decisions in Retrospect

Current State

How I Built a Rails App That Syncs Empire Flippers Listings to HubSpot and Google Sheets

The Origin Story

What the App Does

The Tech Stack

Architecture: Service Objects

The Database Layer: Preventing Duplicates

Fetching Listings: The Pagination Problem

The Sync Orchestrator: Idempotent by Design

HubSpot Integration: The libcurl Adventure

Google Sheets Integration: The Permission Problem

Testing with RSpec: TDD in Practice

The Daily Scheduler

End-to-End Results

Key Learnings

What I'd Add Next

The Bigger Picture

Connecting a Biometric Fingerprint Device to a Rails Web App Using Python — A Complete Walkthrough

👋 Introduction

🏗️ Architecture: The Full Pipeline

🐍 Part 1: The Python Bridge (Gym Laptop Side)

The Problem

Configuration

The Bridge Script

How It Works Step by Step

Auto-Start on Windows

Dependencies

💎 Part 2: The Rails API (Cloud Server Side)

The Route

The Controller

🛡️ Two Layers of Deduplication

🗄️ Database Design

The Bridge Table: trn_member_biometric_mappings

The Attendance Table: trn_member_attendances

🧪 Testing the Full Pipeline

Test with cURL (bypassing the Python bridge)

Test the Python bridge locally

🧩 Edge Cases I Solved

📊 How This Powers the Dashboard

💡 Key Takeaways

🏁 Conclusion

How I Ditched Interakt and Built a Direct WhatsApp Automation Pipeline with Meta Cloud API

The Backstory

What Was Working Before (And What Wasn't)

The Plan: Go Direct with Meta Cloud API

Week One: The Meta Setup Maze

Haptik Was Everywhere

The Payment Method Loop

The Bridge Table: `trn_member_biometric_mappings`

The Attendance Table: `trn_member_attendances`