Operate reliably—from field evidence to model evidence.

Start here

Operating guides

01 / Requirements

Minimal hosting requirements

02 / Setup sequence

Bring the foundation online

1. 1
   Create the database project

   Create a Supabase project, then run every checked-in migration in filename order.

2. 2
   Configure authentication

   Disable public signups, enable email verification, set the redirect URL, and create the initial administrator.

3. 3
   Connect deployment

   Add the environment values to the production host and deploy the main branch.

4. 4
   Enable operations

   Connect the uptime monitor and add the encrypted backup secrets to CI.

03 / Environment

Required application settings

Important: The Supabase secret key is server-only. Never prefix it with NEXT_PUBLIC_ or expose it in browser code.

04 / Security baseline

Secure by default

• A verified one-time email or phone invitation and an active invite-created profile are required before workspace access.
• Row-level security limits operational records to the active organization and permission set.
• Technicians can see all work orders and update assigned work, but cannot create work orders.
• Only Admins can invite, change roles, deactivate or delete profiles, and revoke sessions.
• The final active Admin cannot be demoted, deactivated, or deleted.
• Approval requests and decisions are atomic, named, timestamped, and notified.
• Verified JWT issue time is compared with the member’s session-revocation timestamp.
• Activity and audit ledgers reject updates and deletes; audit events form a SHA-256 chain.
• Work-order lifecycle rules are enforced by both the API and the database.
• Attachment objects remain private and user-scoped with expiring signed links.
• Executable and active-content formats are blocked before upload.
• HTTPS is enforced by the production host.
• Service credentials remain server-side and outside Git.
• API keys are returned once; only SHA-256 digests, scopes, expiry, and revocation state are retained.
• Browser CORS origins are explicit; wildcard credential access is never enabled.
• Webhook destinations require public HTTPS and receive timestamped HMAC-SHA256 signatures.
• Webhook signing secrets are encrypted at rest and rotate with a bounded operational grace record.
• The scheduler secret is stored in Supabase Vault and Edge Function settings, never in browser code.
• Only Admins and Managers can adjust inventory; assigned Technicians may post labor and parts to their work.
• Work-order closure locks stock rows and rejects any transaction that would make inventory negative.
• A unique PM template and scheduled timestamp pair prevents duplicate generated work orders.
• Tenant ownership is immutable after insertion and every operational evidence table uses the same RLS boundary.
• Redis is short-lived and optional; failures fall back to Postgres while authentication remains fail-closed.
• Prometheus metrics omit tenant identifiers and require a server-only bearer secret.
• Mobile pushes use version checks and idempotency receipts; lifecycle and delete conflicts require an explicit decision.
• Analytics exports use a derived-feature allowlist; user identity, free text, locations, filenames, and attachments are excluded.
• Predictive suggestions never change PM schedules automatically; model promotion requires validation evidence and human approval.
• Supply requests derive district and requester server-side; delivery transactions lock rows, reject duplicate completion, and append immutable evidence.
• Position assignments require exactly one matching market, district, or store scope and remain tenant-isolated by row-level security.

05 / Operations

Know when the system needs attention

Configure an external monitor against the production home page and health endpoint. Review Supabase Cron history, Revolution Road scheduler logs, and failed schedule runs; optionally send failure summaries to an alert webhook.