Four levels. Zero confusion.

Project: Your Product Boundary

A project is the top-level container. It represents your product or a specific environment of your product. Everything inside (apps, actors, rooms, access scopes) belongs to that project.

App: A Distinct Real-time Feature

Inside a project, each app represents a separate real-time capability. Apps have their own topic definitions, room configurations, and webhooks.

Why separate apps instead of one big app?

Because different features have fundamentally different requirements:

By splitting these into separate apps, each one gets its own topics, rooms, and webhooks without compromise. Chat's webhooks never fire for GPS pings, and tracking's per-driver rooms never clutter the chat room list. When you need a new feature later, you add a new app without touching the others.

Room: Scoped Data Isolation

Rooms give each user, team, device, or session their own isolated instance of an app's topics. Without rooms, every subscriber to "messages" would see every message from every conversation. Rooms scope the data.

Static vs Dynamic Rooms

Rooms can be static (defined in your app configuration for permanent channels like general) or dynamic (created at runtime through @nolag/core or your own auth service when a new driver signs up or a new team is formed). With @nolag/core, rooms are never created implicitly: the broker refuses an unknown room rather than inventing one, so a typo is a visible error.

Public vs Private Rooms

With @nolag/core, rooms are public by default, meaning any actor with access to the app can connect. When you attach specific actors to a room, that room automatically becomes private. Only the attached actors can access it.

This is how you implement per-user or per-team data isolation without writing any authorization logic:

• Attach a driver to their tracking room, and no other driver can see their GPS stream
• Attach team members to a chat room, and outsiders can't join
• Attach a user to their notification room, and only they receive their alerts

Topic: The Message Channel

Topics are the actual pub/sub channels within a room. Each topic carries one type of data. Subscribers choose which topics to listen to, so a client in the dispatch-team chat room might subscribe to messages but not _typing.

Topic Inheritance

Topics are defined at the app level and inherited by every room. All rooms in your chat app share the same topic structure (messages and _typing), so you configure once and scale to thousands of rooms.