This page catalogues CrowdVision’s user stories and the personas behind them. Each story carries a MoSCoW priority — Must, Should, or Could — reflecting what’s load-bearing for the platform to function at all versus what refines the experience once it does. Nothing currently carries a Won’t; the backlog hasn’t yet had to cut scope.
Acceptance criteria here are functional: they say what must be true, not how fast. Every latency, throughput, or rate target lives on the Quality Attribute Scenario that owns it, and the stories it holds accountable link to it — a number stated in two places drifts in one of them. The two most load-bearing stories carry their criteria in full Gherkin on Acceptance Criteria, where the functional criteria and the QAS target meet in one executable file.
Conventions
User stories are expressed in a simple sentence, structured as follows:
“As a [persona], I [want to], [so that].”
Breaking this down:
“As a [persona]” — Who are we building this for? We’re not just after a job title, we’re after the persona of the person. Max. Our team should have a shared understanding of who Max is. We’ve hopefully interviewed plenty of Max’s. We understand how that person works, how they think and what they feel. We have empathy for Max.
“Wants to” — Here we’re describing their intent, not the features they use. What is it they’re actually trying to achieve? This statement should be implementation free — if you’re describing any part of the UI and not what the user goal is, you’re missing the point.
“So that” — How does their immediate desire to do something fit into their bigger picture? What’s the overall benefit they’re trying to achieve? What is the big problem that needs solving?
Personas
Standard User — a visitor or student who checks the spaces they use: is the study room free, is the hall crowded.
Staff Member — front-line operations, security or facilities staff who watch the live view, respond to alerts, and keep room data current.
Domain Administrator — a facility manager who owns one or more organizations: buildings, member onboarding, alerting policy.
Platform Administrator — CrowdVision’s own operator, who runs the platform rather than using it. No story below belongs to this persona: their concerns are operational qualities of the system itself, and they appear as the source of stimulus in QA-3, QA-4 and QA-5.
Stories
Account & Access
AA-1.Must As a Standard User, I want to create an account with my email and a credential and sign in, so that I can access any organization without creating duplicate accounts.
Given a prospective user provides a valid email and credential, when they submit registration, then an account is created and they can immediately sign in with that credential.
AA-2.Must As a Domain Administrator, I want to onboard a new member directly with the role I choose, so that the right people arrive with the right authority from their first sign-in.
Given a Domain Administrator is onboarding a new member, when they specify the member’s email and a role, then a membership is created for that member with exactly the role chosen, effective from their first sign-in.
AA-3.Should As a Staff Member, I want my access to automatically reflect my employment status, so that joining or leaving the company instantly updates my permissions.
Given a Staff Member’s organization has SSO configured with an external identity provider, when they sign in, then their access is verified against their current identity provider status without requiring a separate CrowdVision credential.
AA-4.Must As a Domain Administrator, I want to split my organization into subdomains, so that campus and department structure is reflected in access control.
Given a Domain Administrator manages an organization, when they create a subdomain, then the subdomain is scoped under the parent organization with its own independent access control.
AA-5.Must As a member of several organizations, I want one sign-in to carry all my memberships, so that I can switch organizations without re-authenticating.
Given a user holds membership in more than one organization, when they switch which organization’s view they’re looking at, then the switch completes and their view updates to the new organization, regardless of how many organizations they belong to.
Edge case:Given a user’s token has expired, when they attempt to switch organizations, then they are required to re-authenticate rather than being silently granted access.
AA-6.Should As a Domain Administrator, I want my domain to be invisible to public discovery, so that only people I invite can find it and request access.
Given a Domain Administrator marks their domain as not visible from outside, when a user without an invitation searches for it, then the domain does not appear and cannot be discovered.
AA-7.Must As a newly registered user, I want to create my own domain right after signing up, so that I can start managing a space without waiting on someone else to invite or provision me.
Given a user has just completed registration, when they create a new organization, then it becomes fully usable — sign-in, building creation, dashboard, alerts all functional — with no manual provisioning step by a Platform Administrator.
Edge case:Given a user attempts to create a domain with a name that is already taken, when they submit the creation request, then the request is rejected and no domain is created.
BT-1.Must As a Domain Administrator, I want to upload a description of my building and have a digital twin built from it, so that the twin mirrors the real structure without developer intervention.
Given a Domain Administrator uploads a valid building description, when the twin-provisioning pipeline processes it, then the twin is created and available for viewing and editing.
Given a Domain Administrator has uploaded a valid building description, when the upload is taken in, then they are told it was accepted and can see when the twin is ready, rather than waiting on an open request with no feedback.
Edge case:Given an uploaded building description is malformed or fails validation, when the upload is submitted, then it is refused outright — no twin is created, nothing is left pending, and the administrator receives an error describing what failed.
Measured by QA-7, Building Upload. Full criteria in Gherkin: Acceptance Criteria — this is the story chosen for executable acceptance testing.
BT-2.Should As a Domain Administrator of a shared structure, I want one building to be visible to several organizations, so that a co-managed structure isn’t duplicated per tenant.
Given a building is scoped to more than one organization, when a member of any of those organizations views the building list, then the building appears for each of them without being duplicated in storage.
BT-3.Could As a Staff Member, I want to rename a room and make certain rooms stand out from the rest, so that the twin reflects how the space is actually used today.
Given a Staff Member has permission to edit a room in their building, when they change its name or mark it as highlighted, then the change is saved and immediately reflected in the twin for all subsequent viewers of that building.
BT-4.Must As a Standard User, I want to see only the buildings of organizations I belong to, so that tenants stay isolated from each other.
Given a user belongs to a specific set of organizations, when they view the list of buildings, then only buildings scoped to at least one of those organizations are shown.
BT-5.Must As a Standard User, I want rooms drawn at their true position and size in the 3D view, so that I recognize the space I’m standing in.
Given a room has defined coordinates and dimensions, when the 3D view renders that room, then it appears at exactly that position and size, matching the underlying model.
BT-6.Could As a Domain Administrator, I want to rename a building, so that the twin reflects real-world naming changes such as a renovation, rebrand, or merger.
Given a Domain Administrator is editing a building they own, when they change its name, then the new name is saved and displayed everywhere the building is referenced for all members of their organization.
BT-7.Should As a Standard User, I want to switch between floors in a multi-floor building, so that I can navigate to the specific level I care about instead of one flat view.
Given a building has more than one floor, when a user selects a different floor, then the 3D view updates to show only the rooms on that floor.
Sensors & Alerting
AL-1.Must As a Domain Administrator, I want exactly one authoritative set of sensor thresholds per building, so that there’s never ambiguity about which limit applied when an alert fired.
Given a building already has a set of sensor thresholds, when a Domain Administrator defines a new threshold set for the same building, then it replaces the existing set rather than coexisting alongside it.
AL-2.Should As a Staff Member, I want to customize sensor thresholds in detail, per room, so that a server room or a lecture hall is judged by its own rules rather than one building-wide default.
Given a building has a default threshold and a specific room has its own override, when a reading is evaluated for that room, then the room’s override is applied instead of the building default.
AL-3.Must As a Staff Member, I want to be notified when a room crosses its threshold, so that I can respond quickly.
Given a staff member is subscribed to alerts for a building, when a room crosses its threshold, then they are notified on every device they have enrolled.
Given a room’s reading returns within bounds before any staff member acknowledges the earlier breach, when the correction is recorded, then no duplicate or contradictory notification is sent for the same breach (only one alert per breach event).
AL-4.Must As a Domain Administrator, I want recorded readings to be incorruptible — a correction is a new reading, never an edit — so that a post-incident review can be trusted.
Given a reading has already been recorded, when a correction is needed, then a new reading is recorded and the original is never modified or deleted.
AL-5.Should As a Staff Member, I want to choose which kinds of alert I receive, separately for each organization, so that my attention is spent only where I asked for it.
Given a Staff Member belongs to more than one organization, when they set their alert type preferences for one organization, then those preferences apply only within that organization and don’t affect any other.
AL-6.Should As a Staff Member, I want to enroll several devices and revoke one without losing my choices, so that replacing a phone is painless.
Given a Staff Member has enrolled multiple devices and configured alert preferences, when they revoke one device, then their alert preferences remain unchanged and their other devices keep receiving alerts.
AL-7.Must As a Domain Administrator, I want alerts to reach only members of the building’s organizations who opted in, so that tenants never see each other’s incidents.
Given a building is scoped to specific organizations, when a threshold breach occurs, then only members of those organizations who opted into that alert type are notified.
AL-8.Must As a Staff Member, I want to connect or remove a sensor from a building or room, so that I control which devices feed data into the twin.
Given a Staff Member is managing a building’s sensors, when they connect or remove a sensor from a room, then subsequent readings are accepted from or rejected for that sensor accordingly.
Live Dashboard
LD-1.Must As a Staff Member, I want to compare rooms side by side in a table, not only navigate them one at a time in the 3D twin, so that I can spot outliers fast across many rooms at once.
Given a Staff Member opens a building’s dashboard, when the table view loads, then every room in the building is listed as a row with its current metric values.
LD-2.Should As a Staff Member, I want to add or remove dashboard columns from a catalog of everything the platform can measure, so that the table fits my operation instead of a default.
Given the platform exposes a catalog of measurable metrics, when a Staff Member adds or removes a column, then the table reflects exactly the chosen set of columns on the next render.
LD-3.Could As a Staff Member, I want my columns kept in exactly the order I arranged them, so that what matters most is always first on screen.
Given a Staff Member has arranged their columns in a specific order, when they reload or reopen the dashboard, then the columns appear in that same order.
LD-4.Must As a Standard User, I want live values to appear without refreshing, so that the dashboard always shows now.
Given a room is currently shown on a building’s live dashboard, when a new sensor reading is ingested for that room, then the updated value appears on screen without requiring a manual refresh.
Given the connection carrying live updates is lost, when a new reading is ingested during the outage, then the dashboard reflects the missed update once connectivity is restored, rather than staying silently stale.
LD-5.Should As a Domain Administrator, I want a freshly registered building to come with a sensible default set of columns, so that the first visit shows data, not configuration work.
Given a Domain Administrator has just registered a new building, when they open its dashboard for the first time, then a sensible default set of columns is already present without any configuration step.
LD-6.Could As a Domain Administrator, I want occupancy and temperature aggregated over a chosen window — day, week, or month; averaged, summed, min, or max — so that I can plan capacity instead of only reacting to it.
Given a Domain Administrator selects a reading window and an aggregation type, when they request the aggregated view, then the values shown reflect exactly that window and aggregation applied to the recorded signals.
LD-7.Must As a Staff Member who relies on a screen reader, I want dashboard data available through accessible markup, so that I can monitor room conditions without depending on sight alone.
Given a screen reader is used to navigate the dashboard, when the table renders, then every data cell and its column header are announced together, including the current value.
AI Assistant
AI-1.Must As a Standard User, I want to ask a plain-language question about the platform or my organizations and get a direct answer, so that I can get unstuck faster than consulting documentation or support.
Given a user has a question about the platform or their organizations, when they submit it to the assistant, then they receive a direct answer grounded in platform knowledge.
AI-2.Must As a Staff Member, I want every claim in an answer to point at the material it came from, so that I can verify it before acting on it.
Given the assistant produces an answer with claims, when any claim in that answer is checked, then it includes a citation pointing to the exact source material.
Given the assistant cannot find source material for a claim, when it would otherwise state that claim, then it omits the claim entirely rather than presenting it without a citation.
AI-3.Should As a Staff Member, I want to ask about a building’s current state — not just how the platform works — and get a real answer, so that “is the west wing still over temperature” doesn’t require switching screens.
Given a user asks about a building’s current live state, when the assistant processes the inquiry, then the answer reflects the building’s live data, not only static platform documentation.
AI-4.Must As a Standard User, I want the assistant to only ever discuss organizations and buildings I have access to, so that its answers never leak someone else’s data.
Given a user’s memberships grant access to a specific set of organizations, when they ask the assistant about any organization or building, then the assistant answers using only data from organizations within that set.
AI-5.Must As a Standard User, I want to be told plainly when the assistant doesn’t know, rather than given a confident but made-up answer, so that I can trust what it does tell me.
Given the assistant cannot ground an answer in cited evidence, when it responds to the inquiry, then it states “I don’t know” rather than presenting an ungrounded claim as fact.
Edge case:Given the assistant has only partial supporting evidence for an answer, when it responds, then it states the uncertainty explicitly rather than presenting a partial answer as fully confident.