Flow Optimisation · Feature state machine

Zone Capacity & Flow Alerts

A single Zone's occupancy state as FlowSnapshot rows accumulate against its configured safeCapacity and warnAtPercent — from quiet, to a predictive warning, to a raised and resolved congestion alert. See SmartFlow.md for the full research and data model behind this.

State diagram

stateDiagram-v2
    [*] --> Suppressed
    Suppressed --> Monitoring : presentCount reaches the k-anonymity floor

    Monitoring --> Elevated : occupancy crosses warnAtPercent, or arrivalsRate predicts it will soon
    Elevated --> Monitoring : occupancy falls back below warnAtPercent
    Elevated --> Congested : occupancy reaches safeCapacity

    Congested --> Alerted : admin/organiser notified
    Alerted --> Acknowledged : admin views the alert
    Acknowledged --> Resolved : occupancy falls back below warnAtPercent
    Congested --> Resolved : occupancy falls back below warnAtPercent (no admin action taken)

    Resolved --> Monitoring : next snapshot window
    Monitoring --> Suppressed : presentCount drops back below the k-anonymity floor

States

State	Meaning
Suppressed	Fewer consenting people present than the k-anonymity floor — nothing is computed or shown.
Monitoring	Normal, below-threshold occupancy for this zone.
Elevated	Occupancy has crossed `warnAtPercent`, or the current arrival rate predicts it will soon.
Congested	Occupancy has reached `safeCapacity`.
Alerted / Acknowledged	The admin/organiser has been notified and has viewed the alert.
Resolved	Occupancy has dropped back below `warnAtPercent`, with or without an admin ever acknowledging it.

Reading the diagram

Suppressed is not an error state — it's the privacy floor: below the minimum-count threshold, no figure is ever computed or shown, so a zone with too little consented activity simply has nothing to report.
Elevated can fire two ways: from the current occupancy percentage, or predictively from arrivalsRate — warn before a room is full, not after.
Alerted → Acknowledged is a human-in-the-loop step on purpose: an alert is a recommendation, never an automated action.
Congested can resolve on its own without ever being acknowledged — the state machine doesn't assume an admin is always watching.