Shipping a Physical Access-Control Integration in Weeks, Starting With a Simulator

The goal

I joined a small IoT platform team as the sole engineer on one epic: integrate a physical access-control system. Locks, key fobs, phone keys, the block list, and the audit trail behind all of it. The vendor's API was large, close to a hundred endpoints, and the only sandbox was shared, slow, and reset without warning. The goal was to deliver the whole integration, validated against real hardware, in weeks rather than months.

The approach

Build the vendor before building the client. A local simulator generated from the OpenAPI spec would unblock development and CI on day one, and once the client worked against it, the live tenant would be used for verification rather than for development.

What I built

The simulator. A full fake of the vendor API built from their spec, with a deterministic fixture that exercises every endpoint, credential enforcement so authentication mistakes surface early, and a browser console for inspecting and resetting state. It runs as a container beside the app and in CI.

The integration, in six pieces. Credential configuration with a verified handshake before a module can be enabled. Zone-to-operator linkage with a nightly lock and key inventory sync. Person lifecycle sync in both directions, with the compliance notes for personal data crossing to a vendor. Key provisioning for real hardware: provision, assign, report lost, unblock, return, re-register. Audit-log ingestion on a cursor with a signed webhook receiver, surfaced on the map and detail pages. And access alerts wired into the platform's alerting engine.

A conformance register. Every place the live server behaved differently from its documentation, eleven in total, recorded with the request that proved it, and folded back into the simulator as a fixture. Two of those entries, an undocumented cap on a per-zone list and a rule about returning a key before cancelling it, would have been production incidents.

The result

Nine pull requests merged in under a month, each with light and dark screenshot walkthroughs against the live tenant as evidence. The team's local development and CI no longer depend on the vendor sandbox at all. The register became the vendor conversation, and a precise list gets an engineer assigned where "your API is flaky" does not.

Takeaways

• Treat a vendor spec as a hypothesis. Build against it to move fast, then verify every call live before shipping.
• A simulator is team infrastructure, not test scaffolding. Build it properly and everyone moves faster.
• Evidence ships with the feature. Screenshots against the real system end the "does it really work" conversation.