Developer-ready checklist for Module 14: Administration & Billing (AdminHQ). It mirrors the earlier modules with acceptance criteria, edge cases, security, observability, and DoD so engineering, QA, and ops can ship confidently.
14. Administration & Billing — Developer Checklist
(AdminHQ – multi-tenant governance, roles, usage limits, subscriptions & billing)
0) Foundations (blockers if incomplete)
Feature flags: adminhq.enabled, adminhq.roles, adminhq.billing, adminhq.usage, adminhq.auditlogs, adminhq.integrations, adminhq.consultant_portal. DB schema: companies, company_profiles, subscriptions, plans, plan_entitlements, billing_history, payment_methods, users, roles, role_permissions, sites, locations, usage_metrics, audit_logs, security_logs, webhook_endpoints. Billing provider: Stripe (primary) with sandbox keys; ACH + invoicing enabled for Pro. Workflow engine: reminder/renewal jobs (e.g., n8n/Celery) + webhook consumers for Stripe events. RLS & policy layer: tenant isolation across all AdminHQ reads/writes. Localization: EN/ES for UI and emails (invoices, dunning, trial expiry).
14.1 Purpose (analytics & governance hooks)
Emit events: account.updated, role.changed, site.added, plan.upgraded|downgraded, invoice.paid|failed, limit.near_threshold, mfa.policy.changed. Insights tiles: plan tier, renewal date, usage vs limits, active users by role. Acceptance: Events visible in analytics dashboards; values match DB.
14.2 Structure
14.2.1 Sections / Tabs
Company Profile, Users & Roles, Sites & Locations, Subscription & Billing, Usage & Limits, Audit Logs, Integrations & Branding. Acceptance: Nav permissions reflect actor (Super Admin / Company Admin / Consultant Admin).
14.2.2 Access Levels
Super Admin (Tellus HQ): global search, impersonate (view-only), plan edits, refunds (guarded). Company Admin: full control within tenant. Partner/Consultant Admin (Pro): multi-tenant switcher with read/limited-write per client. Acceptance: RLS prevents cross-tenant leakage; consultant can only access mapped clients.
14.3 Company Profile
14.3.1 Basic Details
Editable fields: name, address, industry, EIN/DUNS, primary contact; branding (logo/colors) for Pro. Acceptance: Branding reflects in emails and PDFs (where enabled).
14.3.2 Regulatory Identifiers
EPA ID, NAICS/SIC, state license numbers. Acceptance: IDs available to other modules (forms, reports).
14.3.3 Plan Tier Display
Current plan, renewal date, trial status, upgrade/downgrade CTA; pre-expiry banner. Acceptance: Trial countdown accurate; upgrade path works end-to-end.
14.4 Users & Roles
14.4.1 User Directory
List active/pending/deactivated; search + filters (site/location/role); CSV/XLSX import/export. Acceptance: Imports validate unique email and role/site mapping.
14.4.2 Role Management
Defaults: Admin, Manager, Employee, Trainer, Viewer. Custom roles (Standard + Pro): JSON permission matrix per module (CRUD + scope). Acceptance: Changing role updates access immediately; permission tests pass across modules.
14.4.3 Invitations & Deactivation
Invite flow with email; deactivate or reassign; preserve audit trail; MFA enforcement policy (Pro). Acceptance: Deactivated users lose access tokens; audit log records actor + reason.
14.5 Sites & Locations
14.5.1 Site Directory
Add/deactivate within plan limits (Starter=1, Standard=5, Pro=∞); site manager, training progress snapshot. Acceptance: Exceeding limit prompts upsell; creation blocked without upgrade.
14.5.2 Location Management
Nested under site; address, geo, hazard class, storage type. Acceptance: Locations available in Inventory/Plans/Training selectors.
14.6 Subscription & Billing
14.6.1 Overview
Show plan, modules enabled, billing cadence; add-ons (users/storage/AI credits). Acceptance: Entitlements sync to feature flags across app.
14.6.2 Payment Processing (Standard + Pro)
Stripe checkout + customer portal; methods: card, ACH; manual invoicing (Pro). Acceptance: Webhooks: invoice.payment_succeeded|failed, customer.subscription.updated mutate subscriptions correctly.
14.6.3 Invoices & History
List & download PDFs; send to accounting email. Acceptance: SOC2-friendly retention; amounts match Stripe.
14.6.4 Upgrades / Downgrades
Proration calculation; apply immediately or at next cycle; Enterprise quote request. Acceptance: Entitlements reflect within 30s; downgrade-safe guards (e.g., too many sites) guide remediation.
14.7 Usage & Limits
14.7.1 Real-Time Usage Dashboard
KPIs: used/allowed (sites, users), SDS count, trainings completed, storage (GB), AI credits (Pro). Acceptance: Totals reconcile with module tables; refresh ≤ 60s lag.
14.7.2 Overage Alerts
Alerts at 90% of any limit; Auto-upgrade toggle (Pro). Acceptance: Alert sent; auto-upgrade creates Stripe subscription update with confirmation.
14.7.3 Data Retention
Archive inactive users/old data per policy; Pro configurable retention (5–10 yrs). Acceptance: Archival jobs logged; restore path documented.
14.8 Audit Logs & System Activity
14.8.1 System Audit Logs
Record admin actions (who/when/what/before/after). Filters + export (PDF/CSV); API (Pro). Acceptance: Hash chain on logs; export matches filtered set.
14.8.2 Security Logs (Pro)
Login attempts, failures, MFA events, device/IP; anomaly alerts to Sentinel. Acceptance: Suspicious login rule fires (geo-impossible, brute-force).
14.8.3 Change Tracking
Configuration diffs stored; show change summary on each setting page. Acceptance: Diff viewer renders granular changes.
14.9 Integrations & Branding
14.9.1 Email Branding (Standard + Pro)
Custom logo/colors; reply-to domain; preview & test send. Acceptance: Emails reflect brand; DKIM/SPF guidance shown.
14.9.2 External Integrations (Pro)
Webhooks for lifecycle events; token-scoped API keys; rate limits; usage analytics. Acceptance: HMAC signatures verified; retries with backoff.
14.9.3 Partner / Consultant View (Pro)
Tenant switcher; consolidated metrics; client sandboxing. Acceptance: No cross-client data leaks; switch latency < 500ms.
14.10 Notifications & Escalations (by tier)
Starter: Email only — trial ending, storage/limits reached, invoice due. Standard: Email + In-app — user/site limits, payment failures, plan stale. Pro: Email + In-app + Slack/Webhook/SMS — auto-renew complete, API usage threshold, SSO/MFA policy changes. Acceptance: Channel matrix honored; deduped; localized EN/ES.
14.11 Tiering Summary (enforced via entitlements)
Acceptance: Downgrade hides premium UI and blocks restricted endpoints gracefully.
Security Checklist (must-pass)
Tenant isolation (RLS) across all AdminHQ data. Least privilege: permission matrix evaluated server-side; no client-side trust. Billing security: PCI handled by Stripe; we store tokens only; redact PANs. Secret management: rotate Stripe/API keys; per-tenant webhook secrets. Audit immutability: hash chain + write-once storage; time-sync via NTP. MFA policies (Pro): enforceable per role; recovery codes; device enrollment logs. SSO (Pro): SAML/OIDC; just-in-time user provisioning with role mapping. Rate limiting & anti-abuse on exports, API keys, and webhook receivers. Data lifecycle: retention, archival & deletion jobs observable; GDPR export on demand.
QA Test Matrix
Happy Paths New tenant → select plan → Stripe checkout → entitlements applied → add sites/users within limits. Upgrade Standard→Pro → proration applied → Pro features unlocked instantly. Consultant switches clients → views multi-tenant metrics; no leakage. Edge Cases Payment failure → dunning flow; downgrade grace period; restricted exports until paid. Downgrade with over-limit sites/users → guided remediation; block new creations. Invite acceptance with conflicting email (in other tenant) → allow cross-tenant, enforce context switch. SSO enabled → local password login disabled per policy; fallback admin break-glass account. Performance Usage dashboard p95 < 400ms (cached), < 800ms cold. Audit log search < 1s for 100k entries (indexed). Consultant switch < 500ms.
Observability / Alerts
Dashboards: subscription churn, payment failures, overage counts, API/webhook error rates. Alerts: Stripe webhook failures, dunning step timeouts, SSO metadata expiry, audit log write errors. Daily health digest to Super Admins; weekly usage summary to Company Admins.
Deliverables (Definition of Done)
Figma/UI: All AdminHQ tabs, upsell modals, plan-change flows, usage dashboard, logs, consultant switcher. OpenAPI/GraphQL: /admin/company, /admin/users, /admin/roles, /admin/sites, /admin/subscription, /admin/usage, /admin/auditlogs, /admin/securitylogs, /admin/integrations. Stripe integration: Checkout, Customer Portal, webhooks; proration logic; dunning emails. Localization: EN/ES for UI + billing emails/invoices. E2E tests: create tenant → upgrade/downgrade → overage → dunning → recovery; role changes; SSO enable/disable. Admin tools: feature-flag toggles, impersonate (read-only), refund tool (guarded), webhook replay, API key rotation. Rollback plan: disable adminhq.billing|integrations|consultant_portal; core profile/roles/sites remain functional.
✅ Compliance & Business Alignment Summary Want me to proceed with Module 15 – Copilot (AI Assistant & SDS/HazCom Q&A) next?
| Feature | Starter | Standard | Pro |
|---|---|---|---|
| Company Profile | Basic | Editable + Industry | + Regulatory IDs |
| User Management | Invite/Deactivate | + Custom roles | + MFA enforcement & advanced perms |
| Site Management | 1 site | Up to 5 | Unlimited |
| Billing & Payments | Manual | Stripe checkout | ACH + Invoicing + API |
| Usage Tracking | Basic | Real-time dashboard | Real-time + Auto-upgrade |
| Logs | Basic actions | System actions | + Security logs + API |
| Branding | — | Email branding | White-label + consultant portal |
| Integrations | — | Stripe only | Stripe + Webhooks + SSO |
| Notifications | Email + In-app | Email + In-app + Slack/Webhook/SMS |
| Focus Area | AdminHQ Feature | Purpose |
|---|---|---|
| SaaS Governance | Plan entitlements & limits | Revenue integrity & fair use |
| Accountability | Audit & Security Logs | SOC2/ISO audit readiness |
| User Security | MFA/SSO policies | Reduced auth risk |
| Transparency | Usage dashboard & alerts | Self-service clarity |
| Partner Ecosystem | Consultant portal & APIs | Channel/consultant growth |
| Financial Controls | Invoicing & dunning history | Clean finance trails |