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)

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:

1. 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.
2. 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:

1. Add the member in the web app
2. Go to the biometric device, navigate the menu, register their finger manually
3. 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:

1. 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
2. Port 80 was reachable — curl http://spine-fitness.com/iclock/getrequest from the same network returned OK
3. Cloudflare activated successfully — Flexible SSL mode set, domain proxied through Cloudflare
4. Rails ADMS controller was deployed — routes for /iclock/cdata and /iclock/getrequest were live and returning OK
5. 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.

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:

1. Fetches all "For Sale" listings from Empire Flippers' public API
2. Stores listing data in a PostgreSQL database
3. Creates a corresponding Deal in HubSpot CRM for each listing
4. Exports all listings to a Google Sheet
5. Runs the entire sync automatically once per day via background jobs
6. 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

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.

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:

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

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

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

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

1. Use a bridge pattern when hardware can't talk to cloud directly. A simple Python script solved the hardware↔cloud gap.

2. Deduplicate at every layer. Don't trust any single layer to handle it perfectly.

3. Store denied attempts. They're not failures — they're business intelligence.

4. Keep the bridge minimal. Two dependencies (pyzk + requests), one config file, one script. Less can go wrong.

5. Auto-start everything. The gym staff shouldn't need to know Python exists. A .bat file in Startup and it just works.

6. 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!

👉 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:

1. Register 8920 on Meta Cloud API

2. Create message templates

3. Replace Interakt::SendWhatsapp with Meta::SendWhatsapp in Rails

4. 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:

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.

I'm Lakshay, and I built Spine Fitness — a full-stack gym management system using Ruby on Rails that's currently deployed in production and used daily by a real gym in Dwarka, New Delhi.

The gym was managing 200+ members using physical notebooks. Membership renewals were missed, payments were scattered, and attendance tracking was a mess. I built a web platform to replace all of it.

🔗 Live at: spine-fitness.com 💻 Source Code: GitHub Repository

The Problem: Death by Notebooks

Before the software, the gym staff dealt with:

• Member registrations handwritten in registers

• Membership renewals forgotten — lost revenue

• Attendance tracked inconsistently (or not at all)

• Payment history scattered across different books

• Inventory (equipment, supplements) completely untracked

• Member communication required manual phone calls

Result? Human errors, missed renewals, zero visibility, and hours of admin work daily.

The Solution: Spine Fitness

A centralized web platform where gym administrators manage everything digitally — from member onboarding to automated WhatsApp expiry reminders.

Tech Stack at a Glance

⚠️ Update (2026): This system originally used Interakt for WhatsApp messaging. Due to reliability issues, I later replaced it with a direct integration using Meta Cloud API.

👉 Full migration breakdown: How I Replaced Interakt with Meta Cloud API

Architecture Overview

Gym Admin (Browser)
   │
   ▼
Ruby on Rails Application (Render)
   │
   ├── MySQL Database (CleverCloud)
   │
   ├── WhatsApp Messaging (Interakt API)
   │
   ├── Scheduled Jobs (cron-job.com)
   │
   └── REST API: POST /api/biometric_attendances
                    ▲
                    │ HTTP POST (every 20 seconds)
                    │
         ┌─────────┴──────────┐
         │  Python Bridge      │
         │  (bridge.py)        │
         │  Runs on gym laptop │
         └─────────┬──────────┘
                    │ pyzk SDK
                    ▼
         ┌─────────────────────┐
         │  ZK Fingerprint     │
         │  Biometric Device   │
         │  (192.168.1.201)    │
         └─────────────────────┘

The system is multi-language — Ruby on Rails handles the web app and business logic, while a Python script running on the gym's local laptop bridges the physical biometric device to the cloud-hosted Rails API.

Python Biometric Bridge (Runs on Gym Laptop)

The biometric fingerprint device sits on the gym's local network. It doesn't natively talk to cloud APIs. So I wrote a Python bridge script that runs continuously on the gym's Windows laptop:

# biometric_bridge/bridge.py

from zk import ZK
import requests
import time
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()

        last_sent = set()

        while True:
            attendances = conn.get_attendance()

            for att in attendances:
                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": 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:

1. Connects to the ZK biometric device on the local network (192.168.1.201:4370) using the pyzk library

2. Polls attendance logs every 20 seconds

3. Deduplicates locally using an in-memory set (last_sent)

4. Sends each new punch as an HTTP POST to https://spine-fitness.com/api/biometric_attendances

5. Runs as a background process via a .bat file on Windows startup

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

This makes the system truly full-stack — from hardware on the gym floor, through a Python bridge on a local laptop, to a Rails API in the cloud.

🗄️ Database Design: Master-Transaction Pattern

I structured the database into Master tables (static data) and Transaction tables (operational data):

Master Tables:

• mst_members_lists — Member profiles

• mst_membership_plans — Plan types (monthly, quarterly, annual)

• mst_staff_lists / mst_trainer_lists — Staff records

• mst_stock_lists — Equipment & inventory

Transaction Tables:

• trn_member_subscriptions — Active subscriptions with dates

• trn_member_attendances — Biometric punch records

• trn_payments — Payment records linked to subscriptions

• trn_whatsapp_logs — Message delivery tracking

• trn_audit_trials — Full audit log of all actions

This separation keeps queries efficient and business logic clean.

Key Features

1. Member Management

Members get auto-generated codes using a custom GlobalCodeGenerator:

@Lastcode = generate_code(
  table: MstMembersList,
  column: "mmbr_code",
  prefix: "M",
  compcode: session[:loggedUserCompCode]
)

Each member links to subscriptions, payments, and biometric mappings.

2. Subscription & Payment Tracking

The system supports partial payments — a real-world requirement:

def payment_status(subscription)
  paid  = total_paid(subscription)
  final = subscription.ms_final_amount.to_f

  return "PAID"    if paid >= final
  return "PARTIAL" if paid > 0
  "DUE"
end

3. Biometric Attendance

A fingerprint device sends punch data to a REST API endpoint. The system maps biometric IDs to members, deduplicates punches, and validates subscriptions in real-time.

📝 I wrote a full deep-dive on this → [Link to your biometric blog post]

4. WhatsApp Automation

Members automatically receive WhatsApp messages for expiry reminders through a 3-stage pipeline:

Cron Trigger → Background Job → Interakt API → Webhook Delivery Tracking

# Daily cron hits this endpoint
def send_expiry_whatsapp
  return head :unauthorized unless params[:token] == ENV['CRON_SECRET']

  MembershipExpiryWhatsappJob.perform_later(:expiring)
  MembershipExpiryWhatsappJob.perform_later(:expired)
end

Messages are tracked through their full lifecycle:

QUEUED → SENT → DELIVERED → READ (or FAILED)

5. Admin Dashboard

Single-screen overview: Active/Expiring/Expired counts, today's collections, due payments, inventory status — all preloaded in bulk to avoid N+1 queries:

def preload_members
  member_ids = @latest_subs.map(&:ms_member_id).uniq
  @members_map = MstMembersList
    .where(mmbr_compcode: @compcode, id: member_ids)
    .each_with_object({}) { |m, h| h[m.id.to_s] = m }
end

Challenges & Solutions

Key Learnings

1. Real business requirements are messy. Partial payments, expired members punching in, duplicate scans — you don't think about these in tutorials.

2. Background jobs are essential. WhatsApp notifications can't block the request cycle.

3. Audit logging is non-negotiable. When real money is involved, every action needs a trail.

4. N+1 queries become real when you have 200+ members on a dashboard.

5. External APIs need defensive coding. Always handle failures, log responses, and plan for timeouts.

What's Next

• SMS fallback for members not on WhatsApp

• Member-facing mobile view for self-service

• Revenue analytics and trend reports

• Online payment collection

Final Thoughts

Building Spine Fitness taught me that production software for a real business is fundamentally different from side projects. The requirements come from real workflows, bugs have real consequences, and watching a gym owner ditch their notebooks for your app is incredibly satisfying.

If you're looking to build something meaningful with Rails, start by finding a real problem around you. The best portfolio projects are the ones that actually get used.

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

If you found this helpful, drop a ❤️ and follow me for more real-world Rails content!

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.