Requirements

Status: Draft · Part 3 of the solution specification · June 2026

Builds on the solution definition. It states the outcomes and value users must be able to acquire — captured as concrete scenarios and the outcome requirements they exercise — not how the system delivers them.

Deferred to architecture.md (to be written): all implementation-specific detail — technology choices (DSL, persistence, hosting), the internal mechanisms (how reconciliation, propagation and connectors work), the security/access topology, data formats and APIs, and how correctness is proven. This document says what must be true for the user; the architecture document decides how.

Requirements are framed for the protagonist of the problem definition — an Australian regional / mid-sized water owner — and the people who work for it: operations and field staff, asset/capital planners, asset-management leads, data stewards, and administrators.

1. User scenarios

Each scenario names a user, the situation that triggers it, the task, and the value acquired when it succeeds. These are the concrete tests of whether the outcome requirements in §2 are met.

S1 — Plan a shutdown safely. Operations planner. A zone must be taken out of service to replace a main. The planner needs every isolation valve, low point / drain and critical customer for the zone — scattered across GIS, the work system and operational notes, and known to staff by street and local names, not tags. Value: a complete, trusted isolation and notification plan assembled in minutes, with any missing valves or conflicting valve statuses flagged before the crew is on site.

S2 — Target asbestos-cement renewal with confidence. Asset / capital planner. The renewal budget is finite and the worst AC mains must be found first, but AC records are incomplete and contradictory and the work carries asbestos-exposure risk. The planner needs a risk-ranked renewal list from age, material, condition and break history — and, per main, how far the data can be trusted. Value: capital aimed at genuinely high-risk mains rather than at bad records, with the blind spots made explicit — supporting risk-based AC management instead of undermining it.

S3 — Prove asset knowledge to the regulator. Asset-management lead. The utility must show it understands asset condition, criticality and performance, and how complete its asset knowledge is. The lead needs evidence — completeness and consistency of the register for the regulatory view. Value: regulator-ready evidence produced from the same store the utility runs day-to-day, ahead of the deadline rather than scrambled together — turning tightening maturity expectations from a threat into a routine output.

S4 — Respond to a main break. Field responder. A main has burst; it must be found and isolated fast, and the recorded location may be unreliable. The responder needs the best-available picture of the asset and surrounding network with the records’ uncertainty visible, by location. Value: a faster, safer response in which the crew knows which records to trust and where uncertainty is high — instead of searching well away from the actual asset. (STREAM improves the information the crew acts on; it does not physically locate the pipe.)

S5 — Absorb a project / contractor handover. Records / data steward. A capital project hands over a pile of as-builts, datasheets and spreadsheets of mixed quality. The steward needs to bring it in, see where it agrees with and contradicts existing records, decide what to admit to the trusted picture, and resolve key conflicts with a recorded reason. Value: the handover becomes part of a trusted picture rather than a forgotten folder; conflicts are caught at handover — when they are cheap to fix — not at commissioning, when they are not; with an audit trail of what was admitted and why.

sequenceDiagram
    autonumber
    box rgb(219,234,254) People
    actor S as Data steward
    end
    box rgb(224,231,255) Platform
    participant ST as STREAM
    participant Core as Trusted core
    end
    S->>ST: Ingest contractor handover
    ST->>ST: Reconcile vs existing records
    ST-->>S: Conflicts & gaps (with provenance)
    S->>ST: Correct value (reason + author)
    ST->>ST: Correction = top-priority source
    ST->>Core: Admit curated, reconciled result
    Note over Core: originals retained & traceable

S5 as a flow: conflicts surface at handover — when they are cheap to fix — and corrections become authoritative without destroying the originals.

S6 — Serve two teams from one foundation. Administrator. Operations and capital teams need different views of the same data, and work-in-progress must stay separate from what a wider audience sees. The administrator configures a view per audience (structure, what-should-be- present, naming), controls access, and keeps WIP separate from published. Value: one reconciled foundation serves multiple teams without duplicating data or standing up parallel systems, with staged exposure protecting WIP.

2. Outcome requirements

The cross-cutting outcomes the scenarios depend on. Each must hold for the users above.

2.1 Knowing the assets (S1, S4, S5)

• See everything known about an asset in one place, with each value showing its source.
• See what is missing — gaps shown against what should be present for the task, not as silent blanks.
• See where sources disagree — conflicts surfaced, never hidden or silently resolved.
• Trace any value to its origin, so a number can be defended and an error chased to source.
• Find an asset by any name the owner uses — operational common names and locations as readily as engineering tags.

2.2 Judging whether the data is good enough (S2, S3)

• A fit-for-purpose answer to “is my data good enough?” — completeness, consistency and validity reported for a specific use, not as one global score; the same data can pass for one use and fail for another.
• Regulator-ready evidence of asset knowledge — the “prove you know your assets” outcome.

2.3 Improving and correcting the data (S5)

• Resolve a conflict or correct a value with a recorded reason and author, without destroying the originals; the correction becomes authoritative while originals stay visible and traceable.
• Bring in messy external data and control what is admitted to the trusted picture, with an audit trail of what was included or withheld and why.

2.4 Staying current and trustworthy (all)

• The unified picture stays current as sources change — when a source is added, updated or removed, it updates accordingly, including correctly un-linking assets joined only by a source that is now gone, so it never carries stale or wrong unifications.
• The reconciliation can be relied on — its correctness, above all the merge-and-unmerge behaviour everything rests on, must be demonstrable. (How it is proven is an architecture/build concern; that it must be proven before anything is built on it is a requirement.)

2.5 Serving many uses from one foundation (S1, S2, S3, S6)

• Serve different audiences from the same data without forking it.
• Feed the trusted result into the systems the owner already (or will) run — twin, GIS, CMMS — complementing rather than replacing them.

2.6 Bringing in the owner’s sources (S1, S5)

• Ingest from the systems the owner actually runs — GIS, asset/work systems, SCADA, hydraulic models, spreadsheets, databases, document stores and as-builts, condition surveys, lab data. (Exact systems confirmed by discovery — §4.)
• Make sense of structured and semi-structured data directly; bring in harder unstructured sources (scanned drawings, P&IDs) through specialist tools as feeds.
• Mixed units across sources are handled correctly, not silently dropped or misinterpreted.

2.7 Control and accountability (S3, S6)

• Control who can view, change and administer, and stage exposure (WIP vs published).
• Everything is auditable — who changed what, when, and on what source basis.

3. Non-functional outcomes

• Works across the owner’s whole network at their scale without degrading, on a basis that does not preclude growing to very large networks later.
• Stays timely — reflects source changes promptly enough to be trusted for daily decisions.
• Defensible and auditable — every value and every change traceable.
• Portable — a configured view can move between environments (pilot → production, or shared between deployments).

4. Early discovery tasks

To be done early, before connectors and default views are built (solution definition §9):

• Confirm which sources matter by checking the actual systems and versions run by the SEQ beachhead utilities — starting with City of Gold Coast, Urban Utilities and Unitywater.
• Confirm the standards used to shape classification and “what should be present” templates (e.g. the Esri water network foundation, WSAA codes, ISO 55000, AS 5488).
• Confirm the foundational views (operations, renewal, regulatory/maturity, asbestos-cement safety, hydraulic) with real users in the beachhead tier.

5. MVP and phasing

MVP — “show them their own problem.” For one SEQ utility, bring in two or three of its real sources, reconcile them, and deliver the moment at the heart of S2 / S3 / S5: a user seeing the gap-and-conflict view with a fit-for-purpose quality answer on their own data for the first time. This single deliverable is the wedge, the re-education tool, and the proof that the reconciliation can be trusted — and it depends on the reconciliation correctness of §2.4 being established first.

Phase 2 — make it operational. Corrections (S5); additional use-specific views — renewal (S2), regulatory/maturity (S3), AC-safety; more sources; keeping the picture current as sources change; first feeds out to a GIS/CMMS/twin.

Phase 3 — scale and harden. Larger volumes and more sources; the auditable inbound-curation control; broader downstream integration; a second utility.

timeline
    title STREAM rebuild — phasing
    section Foundation
        Pre-MVP : Merge/split spec + automated tests
    section Land
        MVP : One SEQ utility : 2–3 real sources reconciled : Gap-and-conflict view + fit-for-purpose quality
    section Operate
        Phase 2 : Corrections : Renewal / regulatory / AC-safety skins : Stay current as sources change : First feeds to GIS / CMMS / twin
    section Scale
        Phase 3 : Larger volumes & more sources : Inbound-curation control : Second utility

The architecture decisions (DSL, persistence, hosting, security topology) and the mechanisms behind every outcome above are resolved in architecture.md, which must be in place before — or as the first step of — the MVP build.