Climacert‑X certifies facilities using environmental and operational readings. The platform:

• Captures facility context via intake/chatbot and gates pricing until the user signs up.
• Computes a priced BoQ per facility based on its region (multi‑region supported), charging one‑time costs (OTC) at checkout while saving a payment method for renewals.
• Lets Super Admin / Admin run a per-facility Onboarding Wizard: map pin, IoT platform connect + hard‑lock, link devices→assets, verify first reading.
• Activates each facility subscription only when Admin completes onboarding AND Tenant confirms devices are received/installed (AND‑gate).
• Ingests readings via Webhook‑only v2 (HMAC, idempotency, allow‑list), bucketizes (hourly, CO₂ 15‑min), computes monthly rollups, and publishes certification levels.
• Surfaces KPIs and trends on Dashboards, funnels operational/billing issues to Alerts, and enforces billing states (grace/suspended/reactivation pending) with clear UX rules.

Reading order: Roles → Journey → Pricing & BoQ → Payments → Onboarding → Facilities & Devices → Scoring → Dashboards → Alerts → IoT Integration → Tenant Users → Data & APIs → NFRs → Acceptance criteria suites → Test plan → Release checklist.

• BoQ — Bill of Quantities; the items and prices required to deploy a facility.
• OTC — One‑Time Charges (e.g., hardware, install, delivery).
• FX snapshot — Reference rates used to display prices; invoices charge in the region currency.
• Region — A pricing/tax grouping (each country belongs to exactly one region).
• Hard‑lock (IoT) — After pairing a tenant with an IoT platform, switching is disallowed.
• Bucketization — Aggregating readings into fixed time buckets (hourly; CO₂ may be 15‑min).
• Monthly rollup — The historical source of truth for trends and certification calculations.
• Provisional — First 7 days after start of scoring; counts in math but no certificate display.

2.1 Actors

• Tenant Admin — Creates tenant at signup, pays OTC, owns invites, can view/manage billing, confirms "received/installed" during activation.
• Tenant User — Facility‑scoped viewer/editor (per permissions). May confirm "received/installed" if allowed.
• Super Admin — Full platform control: Customers, Pricing, IoT Platforms (connect/lock), Onboarding, Admin management.
• Admin (scoped) — Created by Super Admin; limited to assigned customers/platforms. Onboards facilities & provides support.

2.2 Permissions (matrix excerpt)

*Tenant User access is facility‑scoped and explicitly granted by the Tenant Admin.

• Lead → Intake. Collect facility counts, device families, goals. Pricing stays hidden (counts only).
• Signup & Verification. Email/phone + OTP (e.g., 5‑minute TTL; throttled). Return to priced BoQ.
• BoQ & Checkout. Per‑facility, group by region. OTC charged now, payment method saved for renewals, create pending_activation subscriptions (per facility).
• Onboarding (Admin). Set map pin, connect one IoT platform and hard‑lock tenant pairing, add/link devices→assets, verify first valid reading.
• Activation. Subscription becomes Active when Admin completes + Tenant confirms received/installed.
• Scoring. Stability ~48h post‑activation, then bucketize; monthly rollups drive dashboards & certification.
• Operate. Dashboards, alerts, reports; billing renewals enforce grace → suspended → reactivation pending.

4.1 Regions & currencies

Every country maps to exactly one region (e.g., GCC, Europe, USA). Facilities inherit region from location. Display and invoice in region's native currency. Tenant currency may be shown as reference only.

4.2 SKU model

SKU: {
  sku: string,
  family: enum(device|gateway|connectivity|software|license|installation|delivery|certification),
  label: string,
  unit: enum(each|bundle|month|year|meter|hour|...),
  meta: { provider?: string, deviceFamily?: string, warranty?: string, ... }
}

Quantities derive from intake answers and facility sizing.

4.3 Pricing, taxes, delivery

• Per‑region price lists (canonical storage, e.g., USD) + FX snapshot for display.
• Taxes at invoice time based on facility's region (VAT/GST rules and thresholds).
• Delivery/installation can be per‑facility or per‑region depending on logistics.

4.4 FX snapshot & quote validity

Display prices use the daily FX snapshot; invoices charge in region currency. The BoQ snapshot (items + extended totals) is stored at checkout and is immutable for 30 days (configurable).

4.5 Multi‑facility UI (single page)

• Group facilities by region; show per‑facility breakdown + region subtotal.
• Allow Monthly / Annual per facility; apply annual discounts within the region group if configured.
• Clearly separate OTC (now) vs Subscriptions (recurring).

4.6 Acceptance — Pricing/BoQ

• Given anonymous intake, when viewing pricing, then show counts only (no pricing).
• Given checkout success, when reopening a BoQ, then show immutable snapshot for 30 days.
• Given multiple facilities in the same region, when toggling annual plan, then show a region group with updated subtotals.

5.1 Checkout split

Charge OTC now (PaymentIntent) and save payment method (SetupIntent) for renewals. Create per‑facility subscriptions with state pending_activation and chosen cadence (Monthly/Annual).

5.2 Invoice grouping & proration

Invoices group by region (single currency per invoice). Co‑termination and prorations happen within a region only.

5.3 Renewal states

On failure → Grace (e.g., 7 days) → Suspended. When payment succeeds after suspension → Reactivation Pending until provider webhook arrives → Active.

5.4 Billing UX impact

• Grace: warning banner; "Pay Now" CTA.
• Suspended: certificate/QR hidden, reports blocked, alerts visible read‑only.
• Reactivation Pending: show spinner/info until confirmed.

5.5 Acceptance — Payments

• Given unpaid OTC, when Admin tries onboarding, then block action with "Complete Payment" CTA.
• Given expired card, when renewal triggers, then show Grace banner and Pay Now flow.
• Given suspension, when payment succeeds, then show Reactivation Pending then Active on webhook confirmation.

6.1 Consoles

• Customers: facilities, BoQ state, subscriptions, onboarding status, billing state; filters.
• Admin Management: create Admin (scoped), scope to customers & platforms; full audit.
• Platforms: connect providers, set hard‑lock per tenant.
• Onboarding Wizard: per facility sequence (map pin → lock → devices→assets → first reading → Complete Onboarding).

6.2 Activation AND‑gate

A facility subscription moves from pending_activation → Active only when:

1. Admin presses Complete Onboarding, AND
2. Tenant confirms "Devices received/installed" in the tenant UI.

6.3 Acceptance — Onboarding

• Given platform not locked, when Admin attempts activation, then block with "Lock Platform" step.
• Given no first valid reading, when completing wizard, then prevent activation with inline errors.
• Given Admin complete only, when tenant has not confirmed, then remain pending_activation.

7.1 Hierarchy & pages

Facility → Location → Space → Subspace.
Facility details: Overview, Hierarchy, Certification widget, Devices (with last reading), Alerts, Audit.

7.2 Devices list & drawer

Columns: name, externalId, assigned asset, parameters, last reading, last seen, status.
Drawer: header, breadcrumb, last reading, last seen, parameters (human‑friendly mapping).

7.3 Actions & restrictions

Report Issue, Request Replacement. Images uploaded are passed to support; not persisted long‑term.
No add‑device UI on tenant side. Device linking happens in Onboarding.

7.4 Billing banners

Respect billing states per §5.4; show precise restrictions & recovery CTAs.

7.5 Acceptance — Tenant UI

• Given device offline, when opening drawer, then show status + last seen (absolute + relative).
• Given suspension, when viewing facility, then hide certificate/QR; block reports; keep alerts visible.

8.1 Pipeline

1. Ingest readings via webhook (validate, dedupe, enqueue).
2. Normalize to facility timezone; validate schema & parameter mapping.
3. Bucketize: hourly; CO₂ may use 15‑min buckets.
4. Within‑evaluation vs template + shifts; quorum per asset.
5. Monthly rollups persisted as historical truth.

8.2 Math & thresholds (illustrative)

Facility score = mean of eligible assets (per device completeness gates).
Completeness gates: Silver ≥70%, Gold ≥80%, Platinum ≥90%; Cold/Water stricter (e.g., ≥99%).
Vape KPI: <10% active‑day incidence (if applicable).

8.3 Timing & retention

After activation, require ~48h stability, then start scoring at next local midnight.
First 7 days: Provisional (counts in math; certificate hidden).
Retain monthly rollups indefinitely; purge device×bucket after month close +7d.

8.4 Acceptance — Scoring

• Given newly activated facility, when next local midnight arrives, then scoring begins; first 7 days Provisional.
• Given dashboard 12‑month trend, when fetching data, then use monthly rollups (not raw buckets).

9.1 Widgets

• Summary KPIs (devices online, alerts 30d, certification distribution, facilities, assets, subscriptions).
• Trend (12‑month) from monthly rollups.
• Devices vs Alerts (30d) operational view.
• Top‑5 failing facilities by incidents or score.
• Facility map with level‑colored pins and drill‑down.

9.2 Data sources

Historical → monthly rollups.
Near‑real‑time → device×bucket or lastReading (labeled).

9.3 UX

Filter by date ranges; explicit empty states ("No data for this date").
Drill‑downs route to facility/device/alerts screens.

9.4 Acceptance — Dashboards

• Given no data on date, when filtering to empty day, then show empty message.
• Given pin/cell click, when drilling, then navigate to the correct detail page.

10.1 Categories

• Billing & Payments — renewal failed, grace expiring, suspended, reactivated.
• Device & Certification — device offline, anomalies, thresholds at risk.

10.2 UX

Filter/search, pagination, date ranges.
Pay Now CTA on billing alerts → billing/checkout.
Device/cert alerts → deep link to facility/device.

10.3 Acceptance — Alerts

• Given billing hold, when opening Alerts, then show list + Pay Now CTA.
• Given search/filter, when applied, then return paginated results respecting RBAC.

Super Admins manage regional price lists and tax policies; tenants receive per‑facility, per‑region priced BoQs with 30‑day validity and checkout split (OTC now, subscriptions later).

• Multi‑region per facility with native currencies.
• Taxes per region (inclusive/exclusive); snapshot stored with BoQ.
• Lifecycle: draft_teaser → priced_active → priced_expired → redo → ordered → paid_otc.

11.1 Tenant↔Platform pairing

One IoT platform per tenant; enforced via hard‑lock during onboarding.

11.2 Security

HMAC signature (two modes):

• A) X‑Sig: hex(hmac(secret, raw_body))
• B) X‑Ts: unix, X‑Sig: hex(hmac(secret, ts + "." + raw_body)) and reject if |client‑server| > 5 minutes

Hardening: TLS only, size limit, IP allow‑list, schema validation, duplicate suppression (idempotency keys).

11.3 Behavior

Valid request → 202 Accepted and queued.
Invalid signature/body → 400/401/403.
Rate‑limit → 429 with backoff headers.

11.4 Event schema (example)

{
  "event_id": "prov-12345",         // idempotent unique id from provider
  "device_id": "GW-ACME-001",
  "facility_id": "FAC-001",
  "observed_at": "2025-07-14T10:15:00Z",
  "params": { "co2": 520, "temp": 23.4, "hum": 44.0 }
}

Invite via email/phone; OTP accept with TTL (e.g., 24h).
Assign facility‑scoped permissions (view_devices, view_alerts, view_reports, view_subscriptions).
Enforce on every Facility/Device/Subscription API.
Audit all actions (who, what, when, where).

13.1 Entities

Tenant(id, name, region_id, platform_id, billing_profile, created_at, …)
Facility(id, tenant_id, name, geo, region_id, onboarding_state, billing_state, …)
Subscription(id, facility_id, cadence, status, next_renewal, …)
Device(id, external_id, facility_id, asset_id, template_id, lastReading, last_seen, status, …)
Asset(id, facility_id, type, parent_id, name, …)
Reading(id, device_id, observed_at, params(jsonb), source_id, …)
Bucket(id, device_id, window_start, window_end, stats(jsonb), …)
MonthlyRollup(id, facility_id, month, kpis(jsonb), certificate_level, …)
Alert(id, facility_id, device_id?, type, severity, state, data, created_at, …)
User(id, email/phone, role, tenant_id?, …) and UserFacility(user_id, facility_id, permissions)

13.2 Indexing & retention notes

Hot paths: facility_id, month on rollups; device_id, window_start on buckets; facility_id, created_at on alerts.
Retain buckets current month +7 days; keep monthly rollups indefinitely.

• Transport: TLS 1.2+ everywhere; HSTS; modern cipher suites.
• Auth: OTP for first‑time login; JWT or session with rotation; short TTLs.
• Secrets: KMS‑backed, rotated; per‑tenant platform secrets; least‑privilege.
• PII: Minimize; encrypt at rest; role‑based access to billing data.
• Audit: Immutable audit log for admin actions and billing events.
• DDoS/Rate‑limit: per‑IP and per‑tenant quotas; exponential backoff headers.
• Idempotency: keys on webhook events and checkout actions.

18.1 Subscription

18.2 Onboarding & Activation (AND‑gate)

20.1 Pricing/BoQ

G/W/T tables covering: hidden pricing pre‑signup; snapshot immutability; regional grouping; annual toggle.

20.2 Payments

G/W/T tables for OTC gating onboarding; grace banners; suspension restrictions; reactivation pending.

20.3 Onboarding

G/W/T tables for platform lock, first reading requirement, AND‑gate activation.

20.4 Devices & Tenant UI

G/W/T tables for offline status, last seen rendering, restricted features in suspension.

20.5 Scoring & Dashboards

G/W/T tables for start time, provisional window, rollup‑only history, empty states, drill‑downs.

20.6 Alerts

G/W/T tables for billing CTAs, RBAC‑aware deep links, pagination/filter behavior.