Architecture

Scope of this architecture#

The system separates what a site means from how its systems communicate. A vendor’s camera identifier and message format belong in an adapter and source mapping. Gate B, its relationships, and the meaning of an observation belong in the shared model.

From source systems to applications#

flowchart TD
  Source[Existing hardware and software]
  subgraph Fabric [Integration Fabric]
    Cloud[Cloud connectors]
    Edge[Optional local connectors / Edge]
    Normalize[Validation, identity mapping, normalization]
    Cloud --> Normalize
    Edge --> Normalize
  end
  Source --> Cloud
  Source --> Edge
  Normalize --> Runtime[Ontology Runtime]
  Runtime --> API[Ontology API and SDK]
  API --> Studio[Ontology Studio]
  API --> App[Valanor application]
  API --> Other[Other applications]
  Runtime -. References .-> Evidence[Separate evidence storage]

The connection layer is the choice of interface to an existing system. The Integration Fabric owns the connector and adapter responsibilities around that interface. Edge is one place those connectors can run, not an extra service every cloud connection must pass through.

Cloud and local connections converge at a normalization boundary. Validation checks whether incoming data fits the expected contract. Identity mapping reconciles source identifiers. Normalization translates source-specific fields into shared concepts while retaining their provenance.

Responsibilities of each component#

The existing Valanor application is the first intended consumer. Other applications may include maps, timelines, investigations, analytics, and automation. Application code should use shared concepts when possible rather than branching on a hardware manufacturer.

Cloud connectors and optional Edge software#

A cloud connector can connect to a system that is securely reachable from the cloud, with authorized credentials and appropriate network access. A connector inside the customer environment may be needed for a local management platform, isolated devices, or local processing requirements.

Valanor Edge is the software deployment option for that local path. It does not require a proprietary hardware box. Adapter execution, local processing, health checks, and bounded buffering are responsibilities that may be deployed there, depending on the integration.

Using an existing management platform can reduce the number of direct device connections. That architectural advantage is not a device-count, throughput, or latency guarantee. Capacity must be measured for the actual workload and deployment.

The separate action return path#

flowchart TD
  App[Application requests an action] --> Check{Permissions and constraints satisfied?}
  Check -->|No| Reject[Return rejection]
  Check -->|Yes| Integration[Selected cloud or local integration]
  Integration --> System[Authorized source system]
  System --> Ack[Command acknowledgment]
  System --> Evidence[Result and follow-up evidence]
  Ack --> Record[Action execution record]
  Evidence --> Record
  Record --> Review[Application reviews outcome]

1. An application requests a specific action on an object, for an identified actor and purpose.
2. The API and Runtime evaluate permissions, approvals, capability constraints, current conditions, and availability.
3. An accepted request receives an execution record and is routed through the Integration Fabric to the appropriate adapter.
4. The adapter translates the permitted request into the source system’s command and reports acknowledgment or failure.
5. Follow-up results or observations provide evidence of the physical outcome. The application can inspect that record separately from command acceptance.

For Gate B, requesting an inspection is different from directly sending a device command. A read-only integration might supply camera observations but have no authority or capability to move an agent. The action path cannot infer write access from read access.

Timeouts and lost connections can leave an outcome unknown. An application should not blindly repeat a physical command just because it did not receive an acknowledgment. Retry safety and duplicate handling are part of the action contract still to be specified.

Data ownership, history, and evidence#

Source systems may remain the system of record for their own data. The ontology maintains the shared representation, identities, relationships, and operational history needed by its consumers. Mapping a source into the model does not itself transfer ownership or authorize modifications to the source.

The customer-authorized deployment must define which data can be collected, who can read it, where it is retained, and how corrections and deletion requests propagate. These pages do not establish contractual ownership, retention guarantees, or residency commitments.

Current state should retain its observation time and freshness. Historical records preserve context for earlier decisions. A correction or new interpretation should be distinguishable from the original source report.

Raw video and other large evidence files are separate from structured ontology records. Records can reference an image or clip stored in an authorized evidence system. A structured event does not require continuously uploading every video stream. Evidence access and retention need their own controls, and a reference may outlive the underlying file.

• Implementation status

  Read the narrow verified scope and the remaining design boundaries.

What hardware agnostic means#

Applications should use shared objects and capabilities instead of calling vendor APIs directly. Vendor-specific behavior belongs in adapters. Sources can include devices, existing platforms, software, files, human input, and model outputs.

Hardware agnostic does not mean every device is compatible. An integration needs a usable, authorized interface. Two devices with the same capability label may still differ in operating limits, coverage, accuracy, availability, and the permissions needed to use them.

Choose the right connection path#

Prefer an existing management platform when it provides the required authorized interface. It may consolidate many devices behind one connection, but it might expose only a subset of their data or controls. A file import or human report can also contribute records without becoming a live command connection.

For North Yard, Camera 12 could be read through the existing video platform while Gate B’s status comes from an access system. Those source identifiers are mapped to the shared Gate B context; the camera does not become the gate, and read access to either system does not grant control of it.

Illustrative standards#

These examples show different kinds of interfaces, not interchangeable ways to get every capability. The links point to official standards documentation. No Valanor support is asserted by listing them.

• ONVIF profiles

  ONVIF defines interoperability profiles for IP-based physical security products. Evaluate the required profile and functions, not just the presence of an ONVIF label.

• ONVIF conformant products

  The official product database is the source for checking registered profile conformance. This is separate from compatibility with a Valanor adapter.

• Real-Time Streaming Protocol (RTSP)

  RFC 7826 specifies RTSP version 2.0 for controlling real-time media delivery. A media-session interface is not a complete device-management or physical-control interface; actual device versions must be checked.

• MQTT

  MQTT is a lightweight publish/subscribe messaging protocol. An adapter still needs agreed message meanings, source identities, topic permissions, and freshness rules.

Onboard a source deliberately#

1. Authorize access. Confirm the responsible owner, permitted data, permitted actions, credentials, and network access. Discovery does not supply credentials or permission.
2. Connect. Choose an appropriate adapter and a cloud or customer-environment deployment. Establish the authorized connection.
3. Inspect available data and capabilities. Compare documented functions with what the actual version and account can access. Distinguish read-only access from executable actions.
4. Map identifiers and fields. Reconcile Camera 12’s source identifier, map its site and location, and preserve timestamps, units, and provenance. Resolve ambiguous matches instead of silently merging objects.
5. Validate. Check representative records, duplicate messages, out-of-order updates, stale data, permissions, and failure behavior. Test control operations only within an approved scope.
6. Synchronize. Establish the starting state and subsequent update flow. Track progress and any gaps rather than displaying an incomplete source as complete.
7. Monitor. Observe connection health, last-seen times, errors, capability changes, and source-version changes. Revalidate mappings and capabilities when the interface changes.

Integration capabilities and health#

An integration should make its supported capabilities, operating constraints, and connection health clear to authorized users. Compatibility depends on the actual system and version, not only a manufacturer or protocol name.

A connection can expose observations without supporting control. Confirm the available operations for the intended deployment before building a workflow around them. These pages do not specify an internal adapter interface.

After a firmware or platform change, compatibility may need to be revalidated. Applications should make unavailable or uncertain capabilities visible rather than assuming earlier behavior still holds.

Limits to plan for#

• Missing APIs and inaccessible networks can prevent an integration entirely. A device on the same network is not automatically accessible or authorized.
• Credentials, customer permissions, vendor licensing, and compatible versions are prerequisites, not outcomes of discovery.
• Partial capabilities are normal. An interface may expose live observations but no historical clips, or status but no control.
• Rate limits, outages, and delayed delivery affect what the application can know. Surface stale or missing data instead of treating it as a normal condition.
• Local buffering requires defined storage limits and replay behavior. It does not promise unlimited retention or a fully offline application.
• Hardware with no usable digital interface cannot be guaranteed compatible. An existing gateway may help, but a custom adapter cannot create information or control the source never exposes.

• Cloud and Edge deployment

  Understand where a connector can run and what local deployment does not imply.