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, usage) 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, webhooks, and message logging settings.

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 configuration without compromise. Chat doesn't inherit tracking's fire-and-forget QoS. Tracking doesn't pay for chat's message storage. And when you need notifications 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 via the REST API when a new driver signs up or a new team is formed).

Public vs Private Rooms

By default, rooms are public, 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.