Reference topology
The documented BOX 3.x reference architecture uses containerised microservices in Docker Swarm, with one master node for interfaces, business logic and data, and one or more compute nodes for video processing. The release manifest defines the actual service set.
Service domains
| Domain | Representative services |
|---|---|
| Video and inference | inf-mediaserver, inf-load-balancer, inf-inference |
| Events and decisions | st-event-storage, st-event-filter, st-decision-matrix |
| Cameras and access | st-camera-storage, st-auth, st-access, st-audit |
| Data and files | ds-data-temporary-storage, ds-minio, inf-image-storage |
| Models and media | inf-models-storage, inf-snapshot-processor, va-video-archive, inf-report-video-extractor |
| Interfaces and reporting | ui-nginx, ui-react, ui-rest-to-grpc, report generators |
Storage
PostgreSQL stores operational entities; statistics domains may use their own instance or isolated schema. ClickHouse supports analytical and time-series workloads, Redis handles sessions/cache/operational state, and S3-compatible MinIO stores media and files. Replication, retention and sizing are project-specific. Integrations should use supported APIs rather than direct internal database access.
Requests and events
Nginx and React provide the interface. ui-rest-to-grpc converts incoming REST requests into internal gRPC calls or Kafka commands. Most inter-service event processing is asynchronous through Apache Kafka. Source processing, stored events and an interface request follow different routes.
Observability
Trace camera availability, input and processed frame rate, inference state, Kafka lag, storage delay and consumer delivery. The reference monitoring stack uses Prometheus, Grafana and Loki. Correlate symptoms with version and configuration changes.