Build a structure that lets an integrator manage many clients, many teams and many projects inside one platform, while making sure nobody sees anything they shouldn't, and everybody can find the people they need to work with.

Context

Cervello's customers are integrators and software vendors. They don't use the platform to run one building. They use it to build and operate solutions for their own clients, several at a time.

So a single customer of Cervello might be running a smart-parking solution for one city, a facility-monitoring solution for a shopping group, and a pilot for a prospect, all at once. Different teams. Different clients. Different people who must not see each other's work.

And the buyer is often not the user. The person who signs the contract isn't the engineer configuring devices at 2am. A structure that assumes one account holder with full sight of everything doesn't describe this business at all.

This is the part of the project I took most seriously, and the reason is simple: architecture is the one decision you can't undo later. A wrong structure can't be patched by redesigning screens on top of it. Changing it later means moving every user's mental model at once. So it was worth spending the time to get right, and worth covering the awkward cases before building anything on top.

An organisation landing page showing its projects, teams and members ordered by activity — An organisation's own landing view. One client, or one division, and everything happening inside it.

The instance landing page, listing organisations, teams and members with recent activity — The instance landing view, the top layer. Organisations, teams and members, ordered by what moved most recently.

A team's view of its own work, with its members one tab away rather than in a separate console.

The full member list of an instance, with each member's role — The instance's full member list, which only the instance owner or an instance admin ever sees.

A team's member list, inside the team rather than in an admin console. This is the population a team admin may act on, and all of it.

One person across the whole instance: the teams and projects they are in, and what they touched last. Who-did-what, attached to the person.

An asset hierarchy showing parent and child assets and the links between them — The hierarchy itself. Belongs runs down the tree; relates runs across it.

A list of every asset in a project, each showing what sits beneath it — Every asset in a project in one list, with what sits under each. The user acts on the group, and it applies to every device and every sub-asset beneath it.

An asset dashboard with its telemetry, alarms, events, location and attributes — One asset opened: its telemetry, its alarms, its events, its location, its attributes. The things a device reports alone, gathered at the level a person actually manages.

An alarm tracking view listing alarms across a project with their assigned tasks — Alarms tracked across a whole project, from any device, with the workforce task that answers each one.

A map showing alarms and events by location, with severity, grouped by vertical module — Alarms and events on a map, by severity. The question is never which device number failed.

Decision

Four nested layers

What I found was flat. Devices sat inside an organisation, and that was the whole of it. Neither one was called a layer. The team already knew what a developer building on top would need. A device inside a device. A device wired to another device. What they could not see was how to express it. The architecture engineer had the concept and could write the code, but every noun in his vocabulary was a thing or a sensor, and neither word tells you what is allowed to contain what. That is not a vocabulary a business person can use, and it is not one anybody outside IoT can use either. I took the two dimensions and made them three. Instance → Organisation → Team → Project. The organisation was already there. I added the instance above it and the team inside it, and underneath all of it a way to group devices that did not exist at all. Each layer answers a different question: Every layer has a landing view of its own, showing what is current at that level: recent projects, teams, and members ordered by activity. The structure is only useful if each level answers "what's happening here?" without making someone climb up or down to find out. A team's view lists its projects, sortable by name, activity or device capacity, and a second tab lists its members, so access and activity are managed in the same place as the work rather than in a separate admin console.

Decision

The visibility problem, stated plainly

One of the sharpest problems from research came out of the mouth of an administrator: That's the real difficulty with nested permissions. Restriction is easy to build and easy to over-build. Lock everything down and the structure becomes a cage: people can't perform the job their role exists to perform. So membership visibility is scoped to the layer you're responsible for. An instance's full member list is visible only to the instance owner or admin. @@MOVED@@ An organisation's members are visible at organisation level. A team's members are visible in the team. Each administrator sees exactly the population they are allowed to act on: no more, and crucially no less. And a member profile shows that person across the instance: the teams and projects they participate in, and their recent activity. This is what solves the collision problem. Several people working in the same space with no way to know who did what. Activity isn't a log buried in settings; it's attached to the person and to the layer.

Decision

Assets, and two kinds of relationship

Beneath the permission structure sits a second structure, for the physical world. When I arrived there were only devices. The word was the first problem. This is the Internet of Things, and a thing is not always one object. A sensor that can send and receive on its own is a device, and it is the end of the line. Plenty of sensors cannot talk at all. They read, or they record, and something else has to carry them to the platform. That something else holds others underneath it, and calling it a device says the opposite of what it is. So the model got assets. A device is the sensor that speaks for itself. An asset is the node that carries the ones that cannot. A smart bulb makes it concrete. Some bulbs have the radio inside the bulb. Others have it in the holder, so any bulb you screw in starts reporting. The difference shows up when something fails: if the radio is in the bulb, a dead bulb takes the reporting with it. And the hierarchy has two link types: belongs and relates. Belongs inherits. Relates is a sibling. Street lighting is the clearest case I had. A post carries a morning lamp and an evening lamp, and both of them belong to the post. Post one and post two switch on together, so they relate. Every post on the street may sit under one controller, and that controller is an asset. Nesting is free in every direction: a device beside an asset, an asset beside an asset, a device beside a device. A single parent-child model would have forced users to lie about their own infrastructure to fit the shape the software expected, and the developer would have gone and built a workaround. A platform that means to carry every vertical built on top of it cannot make that the developer's problem. The same principle carries into monitoring: alarms and events are shown by location on a map, with severity, grouped by vertical module, because the question an operator asks is never "which device number failed," it's "what's wrong, where, and how bad."

Result

The structure shipped and is what the platform runs on today in production. Five years on it is still the model, and the shape of it is mine.

What can be claimed is the architecture itself: four nested layers with scoped visibility at each, an activity model that answers who-did-what inside a shared space, and an asset hierarchy that admits infrastructure doesn't always form a clean tree.

Next chapter: Method, the principles, the design system, and the Feature Catalogue.