1. 1) Goal & Preconditions
2. 2) User Flow
3. 3) Functional Requirements (by role)
4. 4) Non‑Functional Requirements
5. 5) Data & Validation Cheatsheet
6. 6) API Stubs
7. 7) UX Copy & Errors (EN/AR)
8. 8) Edge Cases
9. 9) Acceptance Criteria
10. 10) Analytics (events)
11. 11) Open Questions & Gaps
12. 12) Access Matrix (summary)

Generated: 27‑Aug‑2025

Goal. Define roles, scopes, and allowed actions for Tenant Admin, Tenant User, Super Admin, and Admin (Normal/Admin Scoped); and how they interact with BoQ, onboarding, facilities, assets, devices, dashboard, alerts, pricing, and IoT platform connections.

• Preconditions.
  • Roles exist system‑wide; authorization is enforced server‑side on every endpoint.
  • Authentication supports email/phone + OTP; secure sessions; EN/AR localization.
  • One IoT platform is connected per tenant and becomes hard‑locked after connect.
  • Tenant Users require explicit facility access (allow‑list) to see/change anything under that facility.
  • Sensitive actions are audit‑logged (create/update/delete of users, facilities, devices, pricing, platform connect).

2.1 Role lifecycle overview

Roles are assigned at signup (Tenant Admin) or via admin consoles (Super Admin → Admin (Normal), Tenant Admin → Tenant Users). Facility scoping and billing visibility are applied as granular permissions.

2.2 Admin creation and scoping

Super Admin creates Admin (Normal) and scopes them to specific customers (tenants) and optionally platform constraints. Admin (Normal) visibility is limited strictly to assignments.

3.1 Tenant Admin

Scope & creation. The first verified account created during signup owns a new tenant (tenantId) and is assigned Tenant Admin.

Access. Full read on all tenant resources (BoQs, facilities, assets, devices, alerts, dashboard). Billing and checkout actions for the tenant’s facilities. Invite/create Tenant Users and grant them facility‑level access.

Key actions. Complete chatbot intake, view priced BoQ after login, pay OTC, download PDFs. Confirm “received and installed” to unlock per‑facility activation once onboarding is marked complete by Super Admin. Submit device replacement/issue requests.

Limits. Cannot change the IoT platform once connected (hard‑lock).

---

3.2 Tenant User

Scope. Facility‑level access must be explicitly granted; server enforces userHasFacilityAccess(userId, facilityId) on every request. Billing visibility is a separate permission (can be enabled or disabled by Tenant Admin).

Key actions. View facilities, certification status, devices (with last reading), alerts; download reports. Confirm install per facility; request maintenance pause/unpause (affects scoring windows). Alerts page is view‑only except Pay Now navigation on billing alerts.

Limits. Cannot edit assets; only facility image upload allowed.

---

3.3 Super Admin

Scope. Full platform access: Customers, Pricing, IoT Platforms, Facilities/Assets/Devices, Admins.

Key actions. Customers: see all tenants, BoQs and payment states, subscriptions, requests; assign onboarding owner; manage facilities, assets, devices; mark onboarding complete. IoT Platforms: add/connect via OAuth2; once connected, lock per tenant; reconnect if token expires. Pricing: manage regions, prices, taxes, delivery, subscription pricing; BoQs are immutable snapshots. Admins: create Normal Admins; scope them to specific customers and platforms.

---

3.4 Admin (Normal Admin)

Scope. Created by Super Admin; scoped to specific customers (tenants) and allowed platforms. Cannot access IoT Platforms tab or Users tab; only sees data for assigned customers.

Key actions. For assigned customers: view BoQs, Dashboard, Alerts, Facilities/Assets/Devices; add/edit facilities, assets, devices; assist onboarding.

Limits. No ability to manage other admins or IoT platform records; cannot access unassigned customers.

• Security & RBAC. Server‑side authorization on every endpoint; least‑privilege; immutable audit logs on sensitive actions.
• Auth. OTP (short TTL), resend throttles, password strength, lockouts, secure cookies, refresh tokens.
• Performance SLOs. Key pages and APIs target p95 budgets (Dashboard ≤ 500 ms via cache; facility views ≤ 2 s; BoQ compute ≤ 2 s).
• Localization & A11y. EN/AR including RTL, screen‑reader labels and focus states.

Role enum: super_admin | admin_normal | tenant_admin | tenant_user
Billing states: pending_activation | active | grace | suspended | reactivation_pending
Scoring retention: Device×Bucket current month (+7 days purge); Monthly Rollup retained long‑term.

• Tenant & facility scoping. Tenant Admin: all tenant resources. Tenant User: must be in an allow‑list per facility; check on every GET/POST under Facilities and Devices.
• IoT platform lock. tenant.platform_id is immutable after first successful connect.

POST /v1/auth/signup
→ { userId, tenantId, accessToken, refreshToken }

POST /v1/tenant/users
{ name, email|phone, role: "tenant_user" }  → invite

POST /v1/tenant/users/{id}/access
{ facilityIds: [...] }  → grant facility access

POST /v1/superadmin/admins
{ name, email, customers: [...], platforms: [...] }

POST /v1/admin/iot-platforms/connect
{ provider, oauth_code }  → { platformId } (sets and locks tenant.platform_id)

POST /v1/admin/iot-platforms/reconnect
{ platformId }

GET /v1/alerts?tenantId=...&facilityId=...
(view‑only; Pay Now navigates to billing)

• Tenant User without facility access → 403 + guidance to contact Tenant Admin.
• Billing hold → Facility certification/QR hidden, downloads blocked; alerts still visible; Pay Now CTA routes to billing.
• Attempt to change IoT platform after lock → Block action; explain migration is out of scope.
• Normal Admin with no assigned customers → Empty dashboard with CTA to request assignment.

• Tenant creation & ownership
  Given a user signs up via OTP, When signup completes, Then the system creates tenantId and assigns the user as Tenant Admin of that tenant.
• Explicit facility access
  Given a Tenant User without access to Facility F, When they request the Devices list under F, Then the server returns 403.
• Activation AND‑gate
  Given Facility is pending_activation, When Super Admin marks onboarding complete and the tenant confirms install, Then subscription becomes active.
• Normal Admin scoping
  Given a Normal Admin assigned to customers X and Y, When they log in, Then they only see those customers and cannot open IoT Platforms or Users tabs.
• Platform lock
  Given a tenant has a connected platform, When anyone attempts to change it, Then the system blocks the action.

rbac.user_invited { inviterRole, invitedRole }
rbac.facility_access_granted { userId, facilityIds }
admin_customer_assigned { adminId, customerIds }
platform_locked { tenantId, platformId }
tenant_onboarding_confirmed { tenantId, confirmedBy }

• Tenant Admin vs first user mapping — confirm we explicitly assign tenant_admin role to the first signup user for the new tenant.
• Tenant User invitation API — confirm endpoints and whether phone‑only invitations are supported.
• Billing role split — confirm whether all Tenant Users can see Billing or only Tenant Admin (and optionally selected Tenant Users).
• Normal Admin edit scope — can Normal Admin trigger “Mark Onboarded,” or is that Super Admin only?
• Users tab visibility for Tenant Admin — confirm whether Tenant Admin has a Users tab to manage Tenant Users in‑app.

Note: Mermaid diagrams omitted for viewer compatibility; labels sanitized.