Organising 8 engineering teams around a single interface contract

On VisiOne, eight people worked on the same product across very different layers. An IP camera does nothing on its own: the hardware sends a stream, the firmware exposes it, the cloud relays it, the app consumes it. Each team tended to describe the same thing with different words — and to implement it with different schemas.

The problem wasn’t speed

People were moving fast. The problem was the silent agreement missing at every boundary. “Connection state,” for example, was rewritten three times: firmware called it pairing_ready, cloud called it device_available, the Flutter app called it waiting_camera. Same idea, three vocabularies, three bugs waiting to happen.

A document, not a tool

I centralised the interface spec in a single document. Not a Notion, not a Confluence, not a Miro. A versioned file next to the code, that any team could open a pull request against to propose an evolution.

The document described:

• MQTT events and their exact payloads;
• camera states, named exactly once;
• error codes with their business meaning;
• responsibilities: who produces what, who consumes what.

The real effect

Three observations, measured over the life of the project:

1. Cross-team questions dropped. Before: “how does firmware send us pairing?” → asynchronous Slack answer. After: “it’s in the ICD, section 3.2.”
2. Boundary bugs became visible before the code, in PR reviews on the document.
3. Weekly technical reviews were about discussing decisions, not discovering divergences.

What I’d do differently

• version the document with the code from day one, not from week three;
• add a “full-exchange example” section per event — actual pseudo-code reads better than ten lines of description;
• ban interface decisions made verbally without a PR on the document — even the ones that seem obvious.

This is not a new method. It’s the disciplined version of an old principle: when a team grows, coordination costs more than code.