# 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