Skip to content

Core Concepts & Glossary

Shared terminology for the Dory platform. App developers, organization admins, and processor developers will all meet these terms across the System Architecture, Application SDK, API, Portal, Processor SDK, and Orchestrator sections.

The terms are grouped by where they live: who owns and accesses things; how the world is observed and interpreted; what you receive and how it is kept current; and how the producing side runs.

Tenancy & access

Term Definition
Organization The tenant and isolation boundary. An organization owns its members, application credentials, sensors, tags, lenses, and subscriptions, and keeps them isolated from every other organization. Every API call that touches an organization's data resolves to exactly one organization.
User A person with Portal access, authenticated through an OAuth 2.0 / OIDC identity provider. A user can belong to one or more organizations, with one or more roles in each.
Application credential A machine-to-machine credential issued to an application within an organization. An application uses it to obtain access tokens for the Application SDK or direct API calls. The secret is shown at creation and can be retrieved again by a member with permission to manage application credentials. Subscriptions are created by an application credential — the subscribe call is made as one — and each subscription belongs to the credential that created it.
Role A named bundle of permissions assigned to a user within an organization. Roles are either platform defaults or organization-defined.
Permission A single capability (such as reading sensors or writing subscriptions) that gates an action. A user's effective permissions are the union of their roles.

See Identity & Access for how authentication and authorization work.

Sensors, tags & lenses

Term Definition
Sensor A registered, located physical device — for example a camera — owned by an organization. Each sensor has a type, a position on the map, and an area of view — the area it observes, which is what subscriptions match on. A sensor is private (serves only its own organization's subscriptions) or public (may serve any organization's subscriptions; its connection details and metadata are never shown to them). A device that asks for a username and password has a device login, saved with the sensor and write-only: nobody can view it afterwards, and the platform signs in to a camera with it so that processors never receive it. Only active, non-decommissioned sensors are matched. Sensors are the raw-data source.
Area of view The patch of ground a sensor observes — a camera on a corner may watch a street it does not stand on. It is the only geometry a subscription matches on: a sensor is matched when its area of view overlaps a requested region, and where the sensor stands is not consulted. A subscription for * (everywhere you can see) skips the geometry test entirely.
Visibility (public / private) One rule, applied to sensors, lenses and processor templates. A sensor's visibility decides which organizations' subscriptions it may serve; a lens's visibility decides who may subscribe through it; a template's visibility decides which lenses may hold it. Public means any organization; private means only the owning organization. A private template can never sit in a public lens — the platform's database refuses it, not only the Portal. A sensor is private unless it is made public.
Tag An organization's vocabulary entry that defines a kind of event. Tags can be hierarchical (a broad kind containing narrower ones). Tags are how an organization names the things it cares to detect.
Event type A tag used as a subscription filter — identified by its slug. Every requested event type must be a known one; a subscribe request naming one that is not is refused (UNKNOWN_EVENT_TYPE, naming the unknown types).
Lens A named, aliased group of processor templates, created and maintained by organization members who hold permission to manage lenses. The lens chosen for a subscription decides how raw sensor data becomes the events you receive — two lenses over the same sensors can produce different event streams. A lens is owned by one organization and is private (usable only by that organization's subscriptions) or public (usable by any organization's subscriptions; it may hold only public templates). Each subscription uses exactly one lens, named by its alias; consumers pick a lens, never templates. A lens can be edited or deleted at any time: the platform re-checks every subscription hourly and adapts — when another organization makes its lens private, a subscription using it stays active with every event type uncovered until the lens is made public again, and a deleted lens leaves the subscription active with empty coverage for good. A subscription cannot be re-pointed at another lens; create a new one.
Geographic (geohash) region A short code for a rectangular area of the map, 1 to 9 characters long — shorter codes cover wider areas (a continent); longer codes zoom in (a city, then a block) — or * on its own for everywhere you can see. A subscription lists one or more regions and matches every sensor whose area of view overlaps any of them: a camera standing outside a cell but watching into it is matched; where the sensor stands is not consulted. A cell nested inside a coarser requested cell is dropped. The sensors considered are your organization's own plus every organization's public sensors, active and not decommissioned. Limits and refusal codes: see API: subscriptions.

How a sensor is matched — by what it watches, not where it stands, and only if you may see it:

flowchart LR
    R["Your requested regions<br/>geohash cells, or * for everywhere"] --> Q{"Does the sensor's area of view<br/>overlap any requested cell?<br/>(* skips this test)"}
    Q -->|"no"| N1["Not matched —<br/>where the sensor stands is never consulted"]
    Q -->|"yes"| V{"Your organization's sensor,<br/>or a public one?"}
    V -->|"no"| N2["Not matched —<br/>other organizations' private sensors are invisible"]
    V -->|"yes"| A{"Active and<br/>not decommissioned?"}
    A -->|"no"| N3["Not matched"]
    A -->|"yes"| M["Matched<br/>counted in sensors_matched"]

How visibility governs lens composition and who may subscribe — a private template can never be reached through a public lens:

flowchart TB
    subgraph T["Processor templates"]
        TPUB["Public template"]
        TPRIV["Private template"]
    end
    subgraph L["Lenses"]
        LPUB["Public lens"]
        LPRIV["Private lens<br/>of the template's own organization"]
    end
    TPUB -->|"may be placed in"| LPUB
    TPUB -->|"may be placed in"| LPRIV
    TPRIV -->|"may be placed only in"| LPRIV
    TPRIV -. "never — refused by the platform" .-x LPUB
    LPUB -->|"usable by"| ANY["Any organization's subscriptions"]
    LPRIV -->|"usable by"| OWN["Its own organization's subscriptions"]

See Subscriptions & Events for how tags, regions, and lenses combine.

Subscriptions & events

Term Definition
Subscription A standing, server-side request for events, defined by three things: what (event types), where (geographic regions), and how (a lens). Created by an application credential, which owns it. A subscribe request is accepted, not completed: the subscription starts pending, its delivery queue exists immediately, and a worker provisions it shortly after, at which point it becomes active and stays so until you delete it. Deletion is likewise accepted at once and finished in the background. See Subscription status below.
Subscription status pending — accepted; the worker has not finished setting it up, but the delivery queue already exists. active — provisioned; the coverage report may still be empty, which is not an error. deleting — delete accepted; the delivery queue is removed and the processors are being released. error — the subscription could not be set up, or was created before the current delivery system; it carries a subscription error code. Apart from subscriptions created before the current delivery system, only a subscription that has not yet become active ends in error: a re-check of an active subscription that fails is simply tried again the next hour, and the subscription keeps serving you. Whatever the code, delete it and subscribe again.
Subscription error code Why a subscription is in error — one of four codes, shown when you read the subscription and in the list of subscriptions: BROKER_REFUSED (the message broker refused a request while the subscription was being set up; retrying cannot fix it), PROVISIONING_FAILED (setting up kept failing on temporary problems and ran out of attempts after five runs), QUEUE_ORPHANED (the delivery queue could not be created, and could not be cleaned up either; the subscribe request itself was refused with BROKER_UNAVAILABLE), LEGACY_RESUBSCRIBE (created before the current delivery system). A subscription that is not in error has no code. You see only the code and a plain sentence keyed on it — the Portal and the Application SDK show the same sentence — never the platform's technical detail. See When a subscription is in error.
Delivery queue The queue that carries one subscription's events and control messages to its consumer — one per subscription. It exists from the moment the subscribe request is accepted, so you can start consuming before provisioning finishes. It holds a message for up to one hour and keeps at most 10,000 waiting. It is removed during the delete request, so delivery normally stops at once; if the broker cannot be reached at that moment, the worker removes it as the first step of releasing the subscription.
Coverage report The platform's answer to "what did you match for me?". For each requested event type, covered: true or false, with a reason when not covered: LENS_NOT_ACCESSIBLE (the lens no longer exists or is no longer usable by you), NO_SENSORS_IN_REGION (no eligible sensor's area of view overlaps your regions), NO_TEMPLATE_EMITS_IT (no template in the lens with an approved, active version produces that type), NO_COMPATIBLE_SENSOR (a template produces it, but none of the matched sensors is of a type that template supports). Plus four counts: sensors_matched, sensors_served, processors_started, processors_reused. It never contains a sensor id, name, coordinate or processor id. An empty report is expected, not an error: the subscription is active, and the re-check fills it in when the world changes.
Control message A message the platform drops into your delivery queue, alongside events, about the subscription itself: ready (provisioned; carries the coverage report), updated (a re-check changed your coverage; carries the new report), error (setting up failed for good; carries the subscription error code and its plain sentence — sent for BROKER_REFUSED and PROVISIONING_FAILED; the other two codes are found only by reading the subscription). The Application SDK handles them and never passes them to your event callback. Events can arrive before ready.
Worker The platform component that does the slow part of a subscription's life: for subscribe, matching sensors and templates, starting or reusing processors and binding the delivery queue; for delete, releasing the processors; and the hourly re-check. It is also what moves a subscription whose setup keeps failing, or is refused by the message broker, into error. The subscribe and delete requests answer accepted; the worker finishes the job. Exactly one worker runs at a time and it handles its tickets in the order they were sent, so a subscribe and a later delete of the same subscription never cross.
Re-check The hourly re-run of the match for every active subscription, from what you originally asked for. It adds pairs (a sensor installed, published or moved into your regions; a template attached to the lens or approved), drops pairs (a sensor unpublished, decommissioned or moved out; a template detached or revoked; the lens made private or deleted) and releases any processor no other subscription still needs, replaces a processor that failed or was stopped, and repairs a queue or binding the broker lost. You are sent updated only when your coverage actually changed. It is also the backstop that re-drives a subscription stuck in pending or deleting.
Event A JSON object delivered to a consumer — conceptually a versioned envelope wrapping a payload. An event carries what was observed and where. The where is the location the processor's template chose to record — a per-detection estimate or a fixed position — and is informational: the platform does not filter delivered events by it.
At-least-once delivery The delivery guarantee: every matching event is delivered one or more times. Because an event can occasionally arrive more than once, applications should be designed to tolerate duplicates — key on the event's message id.
Event stream The shared bus that carries events from processors to delivery queues. Routing is by which processor published the event and which event type it is: a subscription receives every event of its requested types from every processor serving one of its matched sensors. The location inside an event is not used for routing. The platform manages it; you interact with it only by subscribing.

The statuses a subscription passes through — subscribe and delete are accepted, not completed; the worker moves the subscription on afterwards, and an active subscription never moves to error:

stateDiagram-v2
    [*] --> pending: subscribe accepted · delivery queue already exists
    [*] --> error: created before the current delivery system · LEGACY_RESUBSCRIBE
    pending --> active: worker provisioned it · ready message with the coverage report
    active --> active: hourly re-check · updated message only when coverage changed
    pending --> error: could not be set up · BROKER_REFUSED, PROVISIONING_FAILED or QUEUE_ORPHANED
    pending --> deleting: delete accepted
    active --> deleting: delete accepted · queue removed
    error --> deleting: delete accepted
    deleting --> [*]: worker released the processors

Processors & how they run

These describe the producing side. As a consumer you rarely touch them directly — the platform runs and recovers processors on your behalf — but they explain where your events come from.

Term Definition
Processor A long-running program, built with the Processor SDK, that interprets sensor data and publishes events. One processor runs one sensor with one template. The platform starts a processor the first time a subscription needs that pair, shares it with every other subscription that needs the same pair, and releases it — the container is stopped shortly after — when no subscription needs that pair any more: the last one was deleted, or the hourly re-check dropped the pair from it. A processor keeps in-memory state as it runs.
Processor template A reusable processor definition (its image and configuration) for detecting kinds of events, owned by one organization and private or public. A private template can be placed only in its own organization's private lenses; a public template can be placed in any lens; a public lens can hold only public templates. A template is published in versions, and a version is live only after a platform administrator approves it; revoking the approval stops new processors from starting, and the platform stops running ones shortly after. A lens may combine several templates, overlapping event types included: for each sensor the platform picks the smallest set of templates that covers the requested event types, and each type is served by exactly one of them. Consumers choose a lens by alias and never pick templates directly.
Lens (recap) The consumer-facing grouping of templates. Selecting a lens on a subscription is how you choose how sensor data is turned into events — see Sensors, tags & lenses (private or public — see Visibility there).
Orchestrator The platform component that runs processors and keeps them running: placement, scaling, moving processors between machines, and recovery. See Orchestrator architecture. It starts a processor shortly after the platform records that a subscription needs it, and stops one shortly after it is released or its template's approval is revoked.
Zero-downtime move When a processor must move to another machine, the platform starts the replacement and transfers the processor's state before stopping the original — so there is no gap and no lost state.
Automatic recovery If a processor or its machine fails, the platform brings the processor back automatically, resuming from its last saved state.
State A processor's working data, carried with it across moves and recoveries so it resumes where it left off. The platform captures and restores it; consumers never handle it.
Edge ↔ cloud failover The orchestrator is designed so that a processor can run on edge hardware and fail over to the cloud when the edge goes offline, then fail back when it returns. Today every processor the platform starts runs in the cloud. See Edge failover.

One processor per sensor × template, shared by every subscription that needs the pair and released when the last one is deleted:

flowchart LR
    SA["Subscription A<br/>needs sensor S × template T"] -->|"first to need it: started"| P["One processor<br/>sensor S × template T<br/>held by 2 subscriptions"]
    SB["Subscription B<br/>needs sensor S × template T"] -->|"reused, not started again"| P
    P -->|"A's event types"| QA[("A's delivery queue")]
    P -->|"B's event types"| QB[("B's delivery queue")]
    P -. "A deleted · held by 1, kept running" .-> K["Still running for B"]
    K -. "B deleted too · held by 0" .-> Z["Released · container stopped shortly after"]