Platform Overview¶
Dory is a platform for turning live sensor feeds into meaningful, location-aware events — and for running the processing that produces them reliably, at scale. Sensors stream raw data; processors turn it into typed, located events; and applications subscribe to the event types they care about, from the sensors watching the area they care about. Subscribing is a request the platform accepts at once and fulfils behind the scenes — a subscription worker finds the sensors, starts or reuses the processors, wires your delivery queue, and tells you what it covered.
This page is the whole picture: the pieces, how data flows end to end, and where each audience starts.
The end-to-end flow¶
flowchart LR
S["Sensors<br/>cameras & devices"] --> P["Processors<br/>one per sensor × template"]
P -->|"publish events"| E(["Event stream"])
E -->|"routed by your bindings"| Q[("Your delivery queue<br/>events · control messages")]
Q -->|"consume"| A["Your application<br/>(Application SDK)"]
A -->|"subscribe · status · unsubscribe"| API["REST API"]
API -->|"creates the queue on subscribe,<br/>removes it on unsubscribe"| Q
API -->|"ticket"| T[["Ticket queue<br/>strictly ordered"]]
CLK(("hourly")) -.->|"re-check every<br/>active subscription"| T
T -->|"one at a time"| W["Subscription worker<br/>match · start or reuse · bind · re-check"]
W -->|"processors to start or stop<br/>(picked up on its next poll)"| O["Orchestrator"]
O -->|"runs & recovers"| P
W -->|"binds the queue to<br/>its processors' events"| Q
W -.->|"ready · updated · error"| Q
M["Web Portal"] -. "sensors, lenses, access ·<br/>see & delete subscriptions" .-> API
- Sensors — cameras and other devices at known locations, each with an area of view, the ground it watches — produce raw data.
- Processors interpret that raw data and publish events (
person,vehicle,accident, …), each carrying what was observed and where. One processor runs per sensor and template, and it is shared by every subscription that needs it. - Subscribing. An application subscribes through the REST API, usually via the Application SDK: event types, geographic regions, and a lens alias — one of your organization's lenses, or a public one — that says which processing to apply. The platform checks the request — a refusal comes back at once with a code saying why — then records it, creates its delivery queue and answers at once. The subscription is
pending, and its queue can already be consumed. - Provisioning. A subscription worker takes the request from a strictly ordered ticket queue, one at a time. It finds the sensors whose area of view overlaps your regions — your own, plus any organization's public sensors — picks the lens's templates that emit your event types, starts a processor for each sensor–template pair or reuses a live one, and binds your delivery queue to those processors' events. It then posts a
readycontrol message carrying a coverage report into the queue, and the subscription becomesactive. Nothing matching is not an error: the report says why, per event type, and the re-check fills it in when the world changes. - Delivery. Processors publish to the event stream; your bindings route their events into your delivery queue; your application consumes them. Control messages travel in the same queue, and the SDK keeps them out of your event handler. Events can start arriving before
ready— a processor reused from another subscription may already be publishing. - Behind the scenes. The Orchestrator picks up the processors the worker asks for on its next poll, starts them and keeps them running, and stops the ones the worker releases. Once an hour the worker re-checks every active subscription against the world — a sensor installed or published since, a lens made private, a template revoked, a processor that died — and posts an
updatedmessage when your coverage changes. Unsubscribing is accepted at once: your queue is removed so delivery stops immediately, and the worker releases any processor nobody else uses. The Web Portal and REST API are where you register sensors, define lenses and manage access; the Portal also shows each app credential's subscriptions with their status, and can delete them.
Regions choose sensors, not events
A region selects the sensors whose area of view overlaps it. Every event those processors publish for your event types is delivered; the platform does not filter individual events by where they say they happened.
At a glance, a subscription is pending until provisioned, then active; deleting once you unsubscribe; and error if the platform could not set it up. An error subscription carries an error code — the error control message, the Portal and the SDK explain it in plain words — and the remedy is always the same: delete it and subscribe again. Everything the control messages tell you — status, coverage report, error code — can also be read from the API on demand.
The parts of the platform¶
Dory has two faces — a runtime plane that produces events and a client plane that consumes and manages them.
| Part | Plane | What it is |
|---|---|---|
| Sensors | runtime | Registered physical devices (e.g. cameras), each with a location and an area of view — the ground it watches, which is what a subscription's regions are matched against. Can be kept private or published for other organizations to subscribe to. The raw-data source. |
| Processor SDK | runtime | The library you use to build a processor — a stateful program that turns sensor data into events. (Core of Dory.) |
| Orchestrator | runtime | The control plane that runs and recovers processors — placement, scaling, zero-downtime moves, and failover. (Core of Dory.) |
| Subscription worker | runtime → client | Turns a subscription into processors and bindings: matches sensors by area of view, starts or reuses processors, wires the delivery queue, reports coverage, and re-checks every active subscription hourly. |
| Event stream | runtime → client | The shared bus processors publish to. You never touch it directly — the platform binds your delivery queue to the processors that serve your subscription. |
| Delivery queue | client | One per subscription, created the moment the subscription is accepted. Carries your events and the platform's control messages (ready · updated · error), one way, toward your application. |
| Application SDK | client | The library app developers use to consume events — authenticate, subscribe, wait for coverage, and handle events. Control messages never reach your handler. |
| REST API | client | The programmatic interface behind the portal and the SDK: organizations, access, sensors, lenses — and subscriptions, which are created, read and deleted only here. |
| Web Portal | client | The web UI to manage your organization — members, access, sensors and lenses — and to see each app credential's subscriptions, their status, and delete them. Its visual request builder composes the subscribe request for your code. |
Two planes
The runtime plane (Processor SDK + Orchestrator) runs and recovers processors — it's the core of Dory, detailed in the Processor SDK and Orchestrator sections. The client plane (Application SDK + REST API + Web Portal) is where organizations authenticate, define what they want, and consume the resulting events — detailed in the Application SDK, API, and Portal sections. Between the two sits the subscription worker, which turns a subscription into processors and a wired delivery queue and keeps them current.
What makes Dory different¶
For the people producing events, the platform guarantees a processor keeps running without hand-holding:
- Zero-downtime moves — when a processor must move to another machine, the platform starts its replacement and transfers its state before stopping the original, so there's no gap and no lost state.
- Automatic recovery — if a processor or its machine fails, the platform brings it back automatically, state intact.
- Elastic compute — machines are provisioned when processors need them and released when they don't.
For the people consuming events, the platform handles the plumbing:
- You declare interest, not infrastructure — a subscription says what, where, and how; the platform wires up delivery and keeps it wired: an hourly re-check picks up sensors installed or published later and repairs what broke.
- Location-aware — name the area you care about, from everywhere you can see down to a single block, and the platform finds the sensors whose area of view overlaps it.
- Told, not guessed — when a subscription goes live you get a coverage report per event type, and another whenever the hourly re-check finds it changed.
- Secure and multi-tenant — everything is scoped to your organization. Only what an organization chooses to publish — public sensors, templates and lenses — crosses that line, and a published sensor's connection details and metadata are never shown to other organizations.
Who should read what¶
- App developers — receive events with the Application SDK: manage subscriptions and consume events; or use the REST API directly to create, read and delete subscriptions.
- Organization admins — use the Portal to manage members, access, sensors and lenses, and to see (and delete) each app credential's subscriptions.
- Processor developers — build processors with the Processor SDK.
- Operators — run and observe the platform via the Orchestrator.
- Everyone — skim the Core Concepts & Glossary for shared terminology.
Where to go next¶
- System Architecture — how the pieces connect end to end.
- Core Concepts & Glossary — every term, defined plainly.
- Identity & Access — organizations, members, roles, and app credentials.
- Subscriptions & Events — how a subscription is matched, provisioned, delivered and kept current.