Requirements & Scope

Owner(s): CrowdPM team | Last updated: 2026-03-10 | Status: Production

Requirements & Scope

Purpose of this page

This page describes the current implemented scope of CrowdPM Platform as reflected by the repository README, the OpenAPI contract, the registered Fastify route tree, the frontend surface, and the local-development runbooks. It distinguishes between capabilities that are implemented and demonstrable now, capabilities that are operationally supported but still developer-oriented, and future work that should not be described as finished.

Scope statement

CrowdPM Platform currently supports DPoP-based device pairing and activation, short-lived device token issuance, authenticated ingest, raw payload retention in Cloud Storage, Firestore-backed batch and measurement processing, owner batch/device management, moderation-aware public/private data separation, a Google Maps + deck.gl visualization surface, reproducible emulator smoke tests, and browser-side selected-batch video export from the map UI. The platform is therefore more specific than a generic “user/admin app,” but it is still not a complete long-term civic-data program or polished enterprise platform.

Actors

1. Guest

A guest is an unauthenticated viewer.

Current scope:

• may access the anonymous public batch feed and public batch detail routes;
• may browse public approved data in the map UI, including the “show all public (last 24h)” mode;
• may export video only for publicly available selected batches when signed out;
• may not access owner-only, private, or quarantined data.

2. Authenticated user / device owner

A signed-in user owns one or more devices and interacts with the dashboard, activation flow, and authenticated APIs.

Current scope:

• may approve pending pairing requests through the activation flow;
• may list and manage owned devices;
• may revoke owned devices;
• may list owned batches, inspect batch details, toggle batch visibility, and delete owned batches;
• may query owned measurements through authenticated APIs;
• may configure per-user settings such as default batch visibility and map interleaving behavior;
• may view both owned and public-visible data in the map UI.

3. Moderator

A moderator is a privileged operator for submission review.

Current scope:

• may list recent submissions for moderation;
• may filter submissions by moderation state and visibility;
• may approve or quarantine submissions;
• may access moderation-sensitive batch state that is not available to ordinary users;
• may suspend devices when holding the required moderation permission.

4. Super admin

A super admin is the highest-trust operator reflected in the current API and admin surface.

Current scope:

• has all moderator capabilities;
• may list users from Firebase Auth;
• may update user roles;
• may disable or re-enable users;
• may perform broader administrative role-management workflows than ordinary moderators.

5. Smoke-test operator

A smoke-test operator is a signed-in account explicitly allowed to run ingest smoke tests.

Current scope:

• may access the Smoke Test tab in the frontend when the account matches configured smoke-test users;
• may run the ingest smoke-test endpoint;
• may clean up seeded smoke-test devices and associated ingest files afterward. This is an operational/dev workflow, not a general end-user feature.

6. Device

A device is a non-human actor participating in the platform.

Current scope:

• begins onboarding through /device/start;
• polls /device/token for a registration token after human approval;
• registers long-term key material through /device/register;
• proves possession of its key material with DPoP;
• retrieves a short-lived access token through /device/access-token;
• submits ingest batches to the platform.

Functional requirements

FR-1 Secure device pairing and activation

The system shall support a device authorization flow in which a headless node starts pairing, a human reviews and approves the request in the activation UI, and the device continues only after authorization. The flow shall be bound to device key material rather than a static shared secret.

FR-2 DPoP-bound device token issuance

The system shall issue registration and access tokens only after the device demonstrates possession of the expected Ed25519 key material via DPoP.

FR-3 Authenticated ingest gateway

The system shall accept device-submitted measurement batches through the authenticated ingest path after successful pairing and access-token issuance.

FR-4 Raw payload retention

The system shall persist raw ingest payloads to Cloud Storage so ingest remains auditable and replayable.

FR-5 Batch processing

The system shall process retained data into Firestore-backed measurement structures, including calibration-aware processing when device calibration metadata is present.

FR-6 Batch metadata, moderation state, and visibility state

The system shall record batch-level metadata including count, processed time, visibility, moderation state, and related audit/moderation fields so owner views and public views can diverge correctly.

FR-7 Owner device and batch management

The system shall let authenticated owners list devices and batches, revoke devices, inspect batch detail, change batch visibility, and delete owned batches. Note that source code currently implements owner batch PATCH/DELETE operations in addition to the GET operations emphasized in older docs.

FR-8 Owner measurement access

The system shall let authenticated owners query their device measurements by device, time window, pollutant, and limit.

FR-9 Public approved-data access

The system shall expose anonymous public data only for batches whose visibility is public and whose moderation state is approved.

FR-10 Moderation workflow

The system shall support moderator review of submissions, including listing submissions and changing moderation state between approved and quarantined.

FR-11 User administration

The system shall support privileged administration over user roles and disabled status.

FR-12 User settings

The system shall support authenticated per-user settings for default batch visibility and map interleaving behavior.

FR-13 Map-centric visualization

The frontend shall present processed data through a Google Maps + deck.gl experience, including specific-batch timeline playback and an aggregate “all public data — last 24 hours” exploration mode.

FR-14 Browser-side selected-batch export

The frontend shall support browser-side rendering and download of a selected batch video from the map UI. This is currently a client-side export feature, not a server-side render pipeline.

FR-15 Reproducible smoke-test workflow

The project shall remain runnable locally through the Firebase Emulator Suite and frontend dev server, with a documented smoke-test path and cleanup flow for authorized smoke-test users.

API-aligned implemented feature surface

The current wiki should treat the following route families as part of implemented scope:

• /health
• /device/start
• /device/token
• /device/register
• /device/access-token
• /v1/device-activation
• /v1/device-activation/authorize
• /v1/devices
• /v1/devices/{id}/revoke
• /v1/measurements
• /v1/batches
• /v1/batches/{deviceId}/{batchId}
  • source additionally implements PATCH visibility updates and DELETE batch removal on this route
• /v1/public/batches
• /v1/public/batches/{deviceId}/{batchId}
• /v1/user/settings
• /v1/admin/submissions
• /v1/admin/submissions/{deviceId}/{batchId}
• /v1/admin/users
• /v1/admin/users/{uid}
• /v1/admin/devices/{id}/suspend
• /v1/admin/ingest-smoke-test
• /v1/admin/ingest-smoke-test/cleanup

Frontend surface

The current frontend is not just a single map and a vague admin view. The application shell explicitly exposes:

• Map
• Pairing Guide
• Node
• About
• User Dashboard for signed-in users
• Smoke Test for configured smoke-test users
• Admin for moderators/super admins.

Within that frontend, the user-facing implemented surface includes:

• a user dashboard for device review and batch management;
• a settings panel for default batch visibility and interleaved map rendering;
• a public-data browsing map with batch selection and last-24-hours aggregation;
• selected-batch timeline playback and browser download/export;
• privileged moderation/admin workflows behind role checks.

Data scope

In scope

• PM2.5 measurement batches submitted by nodes;
• device metadata, ownership metadata, and status metadata;
• batch visibility and moderation state;
• moderation reason and audit-style administrative metadata;
• raw ingest payloads retained in Cloud Storage;
• processed measurement rows bucketed for efficient querying;
• per-user ingest/render preferences in userSettings.

Explicitly not established as shipped in current code/docs

Unless later verified and documented, do not present the following as finished current platform features:

• a generalized research export pipeline;
• a polished reporting/export subsystem beyond current batch-oriented views and browser-side map video export;
• a server-side or offline batch-render farm for video production;
• a full mobile-native client;
• an enterprise-grade observability, alerting, and incident-operations stack.

Non-functional requirements

Security

• device onboarding shall require the documented pairing, authorization, registration, and DPoP proof flow;
• privileged routes shall require authenticated users with the required permissions or claims;
• public views shall not reveal private or quarantined data;
• local secrets shall remain outside version control.

Reliability

• ingest should remain durable through raw-payload retention;
• emulator smoke testing should provide a repeatable sanity check after ingest changes;
• cleanup workflows should exist for seeded smoke-test data;
• deployment and local-development procedures should remain separated in documentation.

Maintainability

• frontend and backend should remain aligned through the monorepo and shared tooling;
• route behavior should remain discoverable through the OpenAPI scaffold and source tree;
• docs should be updated when source-level route behavior changes, especially where source currently exceeds older summaries.

Demonstrability

• the project must be presentable without requiring physical hardware;
• a seeded emulator user and smoke-test workflow should remain available for local validation;
• public browsing and map playback should remain demonstrable even to signed-out viewers.

Scope boundary summary

In current scope

• DPoP-based pairing, activation, registration, and short-lived device access tokens;
• authenticated ingest;
• raw payload storage;
• processed measurement persistence;
• owner device and batch management;
• per-user settings;
• public approved-data browsing;
• moderation and user-administration routes;
• device suspension;
• map playback and browser-side video export;
• emulator-based smoke tests and cleanup workflows.

Future scope, not promised as finished now

• richer analytics and reporting workflows;
• broader research/public-data integrations;
• more polished operational UX around device lifecycle management;
• stronger observability and production operations;
• native mobile clients or equivalent dedicated mobile apps.

Acceptance lens for this release

A reviewer should be able to conclude the release meets scope if they can verify:

1. a device can complete the start → authorize → register → access-token flow;
2. ingest produces both retained raw payloads and processed records;
3. an owner can view devices and batches, change batch visibility, and revoke or delete owned resources;
4. public/private plus approved/quarantined separation is enforced;
5. the map can render public or owned batch data and play through a selected batch timeline;
6. authorized smoke-test users can reproduce the documented local smoke-test workflow.