Auto-maintained by Claude Code. Human review before any external use.
Get started (start/) — learning-oriented first-run tutorials (one happy path):
Concepts (concepts/) — the "why/what", linking down into the code-cited dev reference:
- Data model & scope — collections, the org/site/unit/grid 4-tuple, tags, and how tag names resolve to storage
- Time & timezones — epoch-ms everywhere, the sampling grid, UTC day files, and where a timezone actually enters (display only)
- The historian, end to end — how a sample flows connect → store (hot/cold tiers) → serve → act; the three write modes
- How Pulse Chronos stores data — the dense-grid model, on-disk files (hot/cold/blob), fixed precision, and the three read encodings
- How monitoring & alarms work — rules, the four rule types, alarm open/close lifecycle, and auto-rules from tag limits
- How you get notified — how an alarm reaches a person: desktop toast, bell badge, live browser (SSE) feed, email; RBAC scoping
- How Pulse runs its background services — supervision, the watchdog, crash/reboot recovery, and reading service logs
- The agentic AI layer — orchestrator + six sub-agents, intent classification, and the anti-hallucination grounding rule
- High availability, explained — active-passive pair, replication, VIP failover, and the zero-loss shadow cache
- Time & timezones (planned)
How-to Guides (guides/) — task recipes, each leading with the reader's goal:
High Level Design (hld/) — C4-style views:
- System Context — 5-layer architecture: OT sources → connectivity → data → capabilities → application
- Component Architecture — internal component diagram + PI onboarding sequence
- Deployment Views — process topology per deployment (Historian-only / AI bundled / AI separate)
- Network & Ports — all verified ports with bind address, protocol, topology
- Auth & Trust Boundary — route auth groups, role table, JWT model, hardening roadmap & known gaps
- API Server — Warp HTTP server, routes, auth
- Agents — Google ADK, pulse_manager, sub-agents
- High Availability — Active-passive HA, TSDB replication, VIP, role state machine
- Python Services — service manager, python_proxy, registered services
- PI Connector — WebPI metadata, live data, historic data
- MQTT — Mosquitto, async client, WebSocket bridge
- OPC-UA — No native connector; external OPCConnect gateway (OPC-UA → MQTT)
- Monitor — Alarm rules, monitor loop, event tracking
- Notifications Engine — RBAC notifications, SSE stream, OS/webview toasts
- Mail / SMTP — outbound email queue + SMTP client + admin config UI
- CloudSync — local→remote data sync / migration
- Process Manager — Child process lifecycle, HTTP API
- License Portal — Order, activation, renewal, transfer
- Storage Engine — mmap pool, binary format, query engine, aggregator
- Tag Resolver — Filesystem scope mapper (Rust) + semantic NLP resolver (Python)
- SQLite API — Connection pool, dynamic CRUD routes, relationships
- Processing API — Elog Excel reports, EMS API (Python proxy), ingest API
- Backup System — SQLite + timeseries backup, scheduler, restore procedures
- Capacity Planning — Disk sizing formula, service overheads, RAM/CPU, cold-storage/compression
- Benchmarks — Measured ingest, backfill, read-latency and concurrency figures (two-machine field report)
- Cloud Copilot — Docker, Jenkinsfile (standard + Thermax)
- Standalone — Tauri binary, bundling, Windows NSIS
- Historian — Historian-only topology, on-premise (pending docker-compose)
ADRs are descriptive — reverse-engineered from the implementation and cited to it, not prescriptive proposals. New ones are added as dev/adr/NNNN-title.md and listed here.
- 0001 — Active-passive HA with a 6-role state machine
- 0002 — JWT secret from build/env, no plaintext default
- 0003 — Custom memory-mapped binary time-series store
- 0004 — RestrictedPython sandbox for analysis code
- 0005 — Two-layer tag resolution