¶ System Context
5-layer architecture for the Clarity + Pulse platform. Each layer is verified against source files; items without confirmed connector code are omitted.
¶ Architecture Diagram
¶ Visual — 5-layer stack
🎞️ Hand-maintained SVG (
assets/pulse-stack.svg) — a styled rendering of the Mermaid diagram above. The Mermaid stays the regenerable source of truth; update both on structural change. Amber ✦ marks the agent layer (Pulse Copilot), absent in Historian-only installs.
¶ Layer Descriptions
¶ ① OT / Data Sources
External data producers. OSI PI Historian is connected via the PI Web API connector (HTTPS, basic auth). IoT/MQTT devices publish to the Mosquitto broker on port 1883. HTTP edge clients push data directly via the HTTPS ingest endpoint. OPC-UA has no native connector in the source — OPC-UA sources reach the platform via the external OPCConnect gateway, which converts UA reads to MQTT pushes (see OPC-UA).
¶ ② Connectivity Layer
Protocol adapters running inside the Clarity binary. The PI Web API Connector (clarity:backend/src-tauri/src/connectors/webpi/) uses HTTPS with basic auth and supports metadata crawl, live streaming, and historic backfill. The MQTT client (clarity:backend/src-tauri/src/mqtt_services/client.rs) connects to 127.0.0.1:1883 using rumqttc. The HTTP Ingest endpoint (clarity:backend/src-tauri/src/processing_api/ingest.rs) enforces a 10 MB payload limit and 1000 req/min rate limit with a 3600 s token cache.
¶ ③ Data Layer
Persistent storage. The time-series store (clarity:backend/src-tauri/src/api/storage/mod.rs) uses memory-mapped binary day files with a bounded read-mmap pool (512 entries). The SQLite database (pulse-db.sqlite) stores asset hierarchies, users, connections, units, and all dynamic entities managed by the SQLite API.
¶ ④ Capabilities Layer
Business logic and services. Agentic AI runs as a separate process (pulse_multi_agents) connected via the Google ADK proxy. EMS and other Python services are managed by the Process Manager and proxied through Warp. Analytics aggregation runs in Rust (clarity:backend/src-tauri/src/api/aggregator.rs) with 14+ operators. RBAC and auth are handled in clarity:backend/src-tauri/src/auth.rs.
Deployment note: the Agentic AI layer runs only in the AI bundled (edge) / AI separate (cloud) topologies; Historian-only installs have no AI service.
¶ ⑤ Application Layer
Client-facing capabilities. The web frontend is served as static assets from the Warp HTTPS server. Alert management is driven by the monitor subsystem (clarity:backend/src-tauri/src/monitor/). AI Co-Pilot is the browser-facing chat interface proxied to the ADK binary. Asset Onboarding is the PI element crawl and tag mapping UI.
Deployment note: the AI Co-Pilot chat is present only when the agent layer is deployed (AI bundled or AI separate topologies).
Last updated: 2026-05-23 — verified from clarity source code