SCADA-project/docs/vision.md

Product Vision Document – Water System Monitoring Platform

Status: Draft (Pre-MVP)
Date: June 2026
Scope: V1 / Beta

1. Core Vision & Philosophy

• The product helps small water systems (particularly volunteer-run or lightly staffed systems) monitor their infrastructure, detect problems early, and maintain regulatory compliance.
• The system is designed around three layers of intelligence:
  1. Static thresholds (Yellow/Red)
  2. Contextual / seasonal baselines
  3. Relationship-based anomaly detection
• The platform minimizes data egress by doing heavy summarization and intelligent monitoring locally on the edge device.
• The long-term vision includes a specialized AI model trained on water system domain knowledge as a core differentiator.

2. Target Personas & Use Cases

The product targets three primary personas:

Persona	Technical Level	Primary Needs	Dashboard Preference
Board Member / Owner	Low	Quick health status, alerts, confidence	Basic (default)
Licensed Operator	High	Operational visibility, configuration, multi-system management	Advanced (default)
Regulatory / Compliance	Medium	Automated reporting, record keeping, audit readiness	Basic + Compliance views

Key Insight: Licensed operators are expected to be the primary go-to-market entry point. They will often install and configure the system on behalf of their clients.

3. Multi-Tenancy & Access Control (MVP)

• Owner → One water system (1:1 relationship)
• Operator → Can manage multiple water systems
• Water System → One primary Operator (1:1)
• Field Tech → Tied to an Operator; inherits access to the Operator’s systems (with potential future granularity)
• Roles for MVP:
  • Owner: Full access including all account/billing management
  • Operator: High access (everything except billing/account management)
  • User / Field Tech: Lower privileged (mostly read-only, can dismiss alerts)
• Owners and Operators can both act on alerts.
• Field Techs will have a simple boolean for temporary elevated permissions during setup/configuration (MVP).

4. Alert System (MVP)

High-Level Lifecycle

• Created → Managed → Resolved

Alert Creation

• Primary method: AI-assisted interview during sensor onboarding [MVP]
• Secondary method: Simple manual alert editor [MVP]
• Every alert includes:
  • Title
  • Description
  • Troubleshooting / Next Steps (human-readable guidance)
• Alerts support chronological annotations/notes with authorship [MVP]

Alert Behavior

• Two severity levels: Critical (Red) and Warning (Yellow) [MVP]
• Alerts are visible to both Owner and Operator [MVP]
• Both roles can act on alerts (Dismiss/Acknowledge or Mark as Fixed) [MVP]
• Contextual telemetry relationships are defined at alert creation time [MVP]
• Deep links provide additional context when needed [MVP]

Post-MVP: External notifications (email/SMS), advanced suppression logic, per-user notification preferences.

5. Dashboard Strategy (MVP)

Two Dashboard Modes

• Basic Dashboard (10,000 ft view) [MVP]

  • Designed primarily for Owners/Board Members
  • Shows overall system health at a glance
  • Uses Monitored Objects as the primary building block
  • Fixed top section with universal system metrics
  • Lower section contains cards for Monitored Objects

• Advanced Dashboard (2,000 ft view) [MVP]

  • Designed primarily for Operators
  • More data-dense with trends and deeper visibility

Users can override their default dashboard preference.

Monitored Objects (Key Concept) [MVP]

• A Monitored Object is a logical grouping of related sensors.
• This is a first-class concept in the system.
• The Basic Dashboard primarily displays Monitored Objects rather than raw individual sensors.

Post-MVP: More advanced dashboard customization, widget system, and complex visualizations.

6. Data Modeling Concepts

Two important first-class concepts:

1. Monitored Objects

   • Logical groupings of sensors
   • Used for dashboard organization and visualization

2. Contextual Telemetry Relationships

   • Defined at alert creation time (with AI assistance)
   • Used to provide relevant surrounding data when an alert fires
   • Static per alert rule