Edge Processing Module Contract
Keep domain logic independent while making its operation observable, recoverable, and governable.
An edge system becomes difficult to operate when nobody can say where the algorithm ends and where operational responsibility begins. A small, explicit contract between a processing module and the local operating layer protects both sides: the specialist module remains free to own the domain work, while Banalytics can own the surrounding connectivity, state, event flow, monitoring, and controlled response.
Do not turn the operating layer into an undocumented application framework
A computer-vision model, signal-processing routine, optimisation service, or vendor SDK often begins life as a focused piece of domain software. Its team knows the input data, method, accuracy limits, and result semantics. It should continue to own those concerns. Asking it to also reconnect field devices, rotate recordings, account for disk pressure, recover after a host restart, expose remote diagnostics, and feed every business integration usually creates an untestable second platform.
The opposite failure is just as common: an operational platform is asked to understand the algorithm’s internals, model state, or proprietary source code. That makes upgrades, ownership, and support ambiguous. A better design makes the boundary a contract, not another shared layer with vague authority.
In that model, the processing module owns the domain result. The edge operating layer owns the conditions under which the result is produced and used. Banalytics is intended to provide that local operational envelope around cameras, sensors, messaging, storage, events, dashboards, and approved actions.
Give each side a clear job
| Concern | Processing module owns | Operational layer owns |
|---|---|---|
| Domain work | Feature extraction, inference, scoring, optimisation, classification, calculation, and domain-specific validation. | Supplying the agreed input and turning accepted outputs into operational state. |
| Interface semantics | Input assumptions, output schema, error taxonomy, confidence or quality fields, model or algorithm version. | Transport selection, endpoint configuration, credentials, delivery context, and consumers of the result. |
| Runtime health | Whether the module is ready, processing, blocked, failed, or unable to accept work. | Process supervision, host CPU/RAM/disk/network signals, operator visibility, alerting, and recovery runbooks. |
| State and recovery | What checkpoints or domain state are required to resume safely; whether a replay is valid. | Configured retention, local storage capacity, transport reconnection, retry policy, and visible escalation when the contract cannot be met. |
| Operational response | Advice or structured result within the agreed safety and authority boundary. | Events, dashboards, notifications, integrations, and only the pre-approved actions that may follow. |
This is not a claim that every module must be a separate operating-system process. The boundary can be a local service, a native executable, a Python worker, a container, a vendor application, or a component in the same host. What matters is that the responsibility and failure behaviour remain explicit.
Specify more than inputs and outputs
A request and a response are necessary but insufficient. Without health, progress, configuration, and timing semantics, operations cannot distinguish a healthy idle module from a stalled one, or a new result from a delayed replay.
| Contract element | Questions to answer before deployment |
|---|---|
| Inputs | What source, format, units, sampling rate, input window, required metadata, and maximum age are accepted? Does the module pull, receive a push, or read a shared local location? |
| Outputs | What result schema is returned? Include result time, source time, quality or confidence, algorithm version, error state, and a stable correlation or sequence identifier where relevant. |
| Readiness and health | How does the module say that it has started, can accept work, is degraded, or has failed? A live process is not proof that its inputs are current or its output is useful. |
| Progress and checkpoints | For long-running processing, what work is complete, what can resume, and what must be recomputed after a restart? Do not infer these answers from CPU activity alone. |
| Configuration | Which values are supplied by the site, which are immutable module parameters, where are secrets stored, and what configuration change requires a restart or validation run? |
| Timeouts and limits | What is the normal execution time, timeout, concurrency limit, queue limit, input size, and behaviour when those limits are exceeded? |
The contract should be versioned with the module. A change from one output field to another, a different sampling assumption, or a new interpretation of a score is an operational change, not merely an internal code change.
Separate process liveness from data freshness
Operators need at least three independent answers. Is the process running? Is it able to do work? Is the data it is using and producing current enough for the decision? Conflating these states is how a green dashboard can hide a disconnected camera, a stopped sensor, or a queue that is hours behind.
Carry the original source timestamp and the time the result was produced. Where messages can be retried or replayed, add a source sequence ID or another correlation key, then define how the consumer recognises a duplicate. A transport acknowledgement is evidence of delivery, not evidence that the observation is fresh.
The Banalytics System Monitor exposes host CPU load, JVM and system memory, disk capacity, thread counters, WebRTC buffers, and media-stream activity. Those measurements help explain why a local pipeline is late, but the module contract must still expose its own readiness and result-age semantics. For a complete latency path, see Real-Time Edge Analytics.
Design the failure behaviour before the incident
Degraded mode is not simply “offline.” It is the documented set of reduced behaviours a site can safely sustain when one part of the path is unavailable or overloaded. The correct policy depends on the asset and decision; it cannot be copied blindly from another project.
| Condition | Contract decision | Example operating response |
|---|---|---|
| Remote service or WAN unavailable | State what continues locally, what is buffered, and what external delivery may be delayed or discarded. | Continue local acquisition, configured recording, and local rules; show remote-path degradation when it returns. |
| Input source is stale or disconnected | Define the freshness threshold and whether the last valid state may be displayed, used for advisory analysis, or must be rejected. | Emit a data-quality event instead of treating the last value as live. |
| Module is slow or unavailable | Choose timeout, fallback, sampling, batching, queue cap, or a safe stop. State who may restart it and at what scope. | Mark the analytic result unavailable while preserving source evidence for review if storage policy allows. |
| Storage is constrained | Define retention priority: which records are protected, which fidelity can be reduced, and when acquisition must stop rather than corrupt evidence. | Alert before the threshold, prune only within the approved retention rule, and make any loss visible. |
| Downstream consumer is slow | Define whether to retry, retain, aggregate, sample, or drop. Specify whether consumption must be idempotent. | Keep a bounded local handoff and surface backlog age rather than silently growing an unbounded queue. |
Safety, protection, motion control, and other certified or deterministic control functions must retain their own authority. A custom analytics module or orchestration rule should remain advisory unless the system owner has independently engineered and approved a bounded control path.
Use Banalytics as the operational wrapper, not as the domain algorithm
A practical Banalytics design keeps device acquisition local, hands an agreed payload to the specialist module, receives a structured result, and turns that result into an event, dashboard state, retained record, notification, or approved integration. The module may use an explicit local interface such as ZeroMQ Socket, or a publish/subscribe boundary through the local MQTT Server, when that better fits the workload.
For a separately running helper, the Process component can provide an explicit supervised integration point. Its configuration should not replace the helper’s own health endpoint, permissions, or restart policy; instead, document how those mechanisms work together. Banalytics components, tasks, events, and actions keep the surrounding device state and response workflow inspectable without requiring the processing team to rewrite its code.
The Event Manager can convert an accepted module result into configured local rules and actions. This allows a site to change a recipient, threshold, dashboard, notification, or external handoff without modifying a model. It does not make an ambiguous result safe by itself: the contract still needs source time, quality, ownership, and a defined response authority.
Start with one representative path
- Name the outcome. Identify the physical source, the decision it informs, the response owner, and the time within which the result is useful.
- Write the contract. Capture inputs, outputs, source time, quality, health, progress, configuration, limits, error states, and versioning in one reviewable document.
- Set resource and retention budgets. Define CPU, memory, disk, queue, retry, and data-loss policies under representative load rather than assuming an unlimited host.
- Prove degraded behaviour. Disconnect a source, interrupt the WAN path, delay a consumer, fill a controlled test store, restart the module, and verify that the visible state remains truthful.
- Connect operational response. Use Banalytics events, dashboards, history, and approved actions only after the module result and failure behaviour are understood.
- Version and review changes. Treat a changed schema, model, threshold, transport, retention rule, or restart policy as a change to the operating contract.
This approach gives domain teams room to innovate and gives site operators an environment they can observe, recover, and explain. It is also a practical way to bring research, vendor software, and proprietary enterprise modules into physical operations without making any one party responsible for everything.