From a2e396b8aa534466b5c1fcd845b33ffdbcaaef7a Mon Sep 17 00:00:00 2001 From: Ty Date: Fri, 19 Jun 2026 20:18:47 +0000 Subject: [PATCH] Update vision.md with full detailed content --- docs/vision.md | 109 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 90 insertions(+), 19 deletions(-) diff --git a/docs/vision.md b/docs/vision.md index de9e883..db0837e 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -1,28 +1,99 @@ -# SCADA for Small Water Systems - Vision +# Product Vision Document – Water System Monitoring Platform -**Status**: Draft +**Status**: Draft (Pre-MVP) +**Date**: June 2026 +**Scope**: V1 / Beta -## Overview +## 1. Core Vision & Philosophy -A modern, affordable monitoring and alerting platform for small water systems that combines edge computing, hybrid AI, and thoughtful multi-tenancy design. +- 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. -## Target Users +## 2. Target Personas & Use Cases -- Small water system board members (non-technical) -- Licensed water system operators managing multiple systems -- Homeowners with private wells serving multiple connections +The product targets three primary personas: -## Core Value Propositions +| 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 | -- Significantly lower ongoing data costs through intelligent local processing -- Usable by both technical and non-technical stakeholders -- Proactive alerting instead of reactive monitoring -- Designed specifically for the economic realities of small systems +**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. -## Key Architectural Principles +## 3. Multi-Tenancy & Access Control (MVP) -- Low-egress by default -- Hybrid AI (edge + cloud) -- Strong multi-tenancy with clear RBAC -- Tamper-evident field hardware -- Practical reliability over theoretical perfection \ No newline at end of file +- **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 \ No newline at end of file