At NUS Technology, we design and build Operations Backbone Platforms for businesses with complex workflows. Often, this requires Complex System Integration—connecting legacy systems, payments, and real-time hardware into one unified platform.

We pride ourselves on tackling the integrations that off-the-shelf SaaS avoids. Recently, our engineering team faced exactly this kind of challenge for a large-scale workforce management platform: seamlessly integrating ZKTeco biometric time-and-attendance hardware into a modern .NET 7 cloud infrastructure.

The catch? The vendor provided a raw PUSH protocol specification, but absolutely no .NET Core SDK. Here is how our team bypassed the missing SDK, built a highly scalable TCP server from scratch, and tamed the unpredictable nature of real-world hardware.

---

The Challenge: Hardware Integration Without a Safety Net

Integrating hardware directly into a cloud backend is fundamentally different from integrating standard REST APIs. For this project, we faced several significant hurdles:

1. No Native SDK: We had to implement the raw ZKTeco PUSH protocol directly over TCP, handling HTTP/1.1 handshakes embedded inside raw sockets.
2. Short Connection Model: Unlike standard IoT devices that maintain a persistent WebSocket or MQTT connection, these devices use a "short connection" model. They connect, send a request, receive a response, and immediately disconnect.
3. Strict Multi-Tenancy: The platform serves multiple companies (tenants). A single server had to handle incoming connections from hundreds of devices belonging to different tenants, ensuring absolutely zero cross-contamination of data.

The Architecture: A Multi-Tenant TCP Server

To handle the load without heavy persistent connection pools, we built a sequential TCP Listener that processes short connections incredibly fast.

The most critical requirement was tenant isolation. How do you ensure that a fingerprint scan from Company A's device doesn't end up in Company B's database when they all hit the same TCP server?

We implemented a two-layered isolation strategy:

1. Host-Header Routing: Each tenant configures their devices to point to a unique subdomain (e.g., tenant-a.platform.com:80). Our TCP server parses the HTTP Host header inside the raw TCP stream to identify the tenant.
2. Schema-Switching & Scoped Dependency Injection: For every single request, the server uses IServiceScopeFactory.CreateScope() to generate a completely new execution context. It dynamically switches the TenantDbContext schema to match the tenant, guaranteeing isolated data operations.

Architecture Flow

Ensuring Zero Data Loss in Unstable Environments

In the real world, hardware loses power, and construction site networks drop out. Because these devices use a short-connection model, the server cannot independently open a connection to push a command (like "Add New User" or "Update Access Rights") to the device.

To solve this, we built a Database-Backed Command Queue Pattern:

• When an admin performs an action on the UI, the command is saved to the database with a null return value.
• When the device comes online and polls the server, it retrieves pending commands, executes them, and replies with a POST /iclock/devicecmd to acknowledge completion.
• Auto-Recovery: If a device reboots, it sends a DevFirstRequest. Our server responds with a configuration payload demanding the device re-upload specific data tables (e.g., "User\tTransaction"). The device automatically pushes all data generated while it was offline, ensuring no attendance logs are ever lost.

Taming Undocumented Hardware Behaviors

Building the architecture was only half the battle. The real test of our engineering maturity was handling undocumented firmware behaviors and edge cases that only reveal themselves in production.

Our team successfully identified and built fallbacks for several hardware quirks:

• Schizophrenic Payloads: Depending on the firmware version, the exact same real-time log data could arrive in two entirely different formats: a tab-separated positional format (rtlog) or a key-value format (transaction). We built dynamic parsers to detect and normalize both at runtime.
• Time Encoding Chaos: Some fields reported time as standard ISO strings, while others randomly used Unix timestamps (seconds since epoch).
• Corrupted Base64 Images: When devices sent biometric photos (ATTPHOTO), the Base64 strings occasionally lacked proper padding, which would crash standard decoders. We implemented a custom padding normalizer.
• Hardware Bottlenecks: We discovered that older "InBio" models would silently fail if sent multiple commands in a batch. We implemented runtime detection via device registries to limit these specific models to processing one command per poll.

The Impact

By opting to build a custom TCP server from the ground up rather than relying on unreliable third-party middleware, we delivered a highly stable, multi-tenant hardware integration that runs flawlessly in production.

This project perfectly encapsulates our ethos at NUS Technology. We don't just write code; we dive deep into low-level protocols, manage infrastructure complexities, and build resilient systems that anticipate real-world failures.

Are Your Operations Outgrowing Your Software?

If your business relies on legacy hardware, complex payment integrations, or fragmented systems that off-the-shelf SaaS avoids, you need more than just an app—you need a reliable Operational Backbone.

We operate like an internal engineering team, owning reliability, performance, and continuous improvement as your operations scale.

Contact to schedule a Strategy Session with NUS Technology today and discuss how we can unify your complex workflows and hardware into one seamless operation.