Skip to main content

Environment Overview

Last reviewed: 2026-05-13
Maintained by: Engineering

This page is the practical environment map for Zgrid. It intentionally uses placeholders for hosted URLs and does not expose real secrets, real DSNs, or private dashboards.

Status legend:

  • Implemented: current behavior is documented in repo workflows and env contracts
  • Partial: some parts of the environment behavior are documented, but not every surface is fully automated or fully described
  • Template-ready: a safe placeholder is included so the team has a slot to fill once a stronger standard exists

Local​

Status:

  • Implemented

Purpose:

  • day-to-day development
  • reproducible local debugging
  • migrations, seed flows, and smoke verification before opening a PR

URL pattern:

  • API: http://localhost:3000
  • Back Office: http://localhost:3002
  • Manager Desk: http://localhost:3001
  • Docs Portal: http://localhost:3004

Mobile config notes:

  • set EXPO_PUBLIC_API_URL when needed for your device/emulator target
  • iOS/macOS-friendly local default is http://127.0.0.1:3000/api
  • Android emulator-friendly local default is http://10.0.2.2:3000/api

Database notes:

  • local PostgreSQL runs through Docker in the documented team workflow
  • the common local port in current docs is 5433
  • local schema work should go through migrations, not manual schema edits

Email provider mode:

  • use EMAIL_PROVIDER=dev_log
  • do not add a real RESEND_API_KEY locally unless you are intentionally testing delivery

R2 notes:

  • use environment-managed local test values only when attachment flows need them
  • do not commit storage credentials

Sentry environment value:

  • local
  • current docs recommend keeping Sentry disabled locally unless intentionally testing it

Important safety notes:

  • keep local secrets and DSNs out of source control
  • run migrations before testing issue or service-request flows against an older database
  • prefer placeholder sender and support addresses in local email config

Staging​

Status:

  • Implemented for API and Manager Desk deployment workflow
  • Partial for Back Office deployment automation coverage in current repo docs

Purpose:

  • hosted validation before production
  • environment contract checks during manual deployment
  • QA, acceptance checks, and integration verification with hosted services

Hosting note:

  • the API hosting standard in this docs portal is Render

URL pattern:

  • API: https://api-staging.example.invalid
  • Back Office: https://bo-staging.example.invalid
  • Manager Desk: https://md-staging.example.invalid

Mobile config notes:

  • hosted mobile builds should point EXPO_PUBLIC_API_URL at the staging API origin
  • Expo/EAS environment variables should be used instead of hardcoding hosted URLs into source

Database notes:

  • use a dedicated staging database
  • never point staging at a local database
  • migrations should run against the staging environment before relying on newly added schema paths

Email provider mode:

  • current env contract expects EMAIL_PROVIDER=resend

R2 notes:

  • use a staging-specific bucket or logically isolated object-storage configuration
  • do not reuse production credentials in staging

Sentry environment value:

  • staging

Important safety notes:

  • staging should use environment-managed secrets only
  • treat staging user data carefully even when it is not production
  • confirm hosted origins and cookie settings before testing auth behavior

Production​

Status:

  • Implemented for API and Manager Desk deployment workflow
  • Partial for Back Office deployment automation coverage in current repo docs

Purpose:

  • live runtime environment for real users and production operations

Hosting note:

  • the API hosting standard in this docs portal is Render

URL pattern:

  • API: https://api.example.invalid
  • Back Office: https://bo.example.invalid
  • Manager Desk: https://md.example.invalid

Mobile config notes:

  • production mobile builds should use production Expo/EAS environment variables
  • production API endpoints must not be compiled from local defaults

Database notes:

  • production must use a dedicated managed PostgreSQL instance
  • migration safety matters more than speed; test schema changes before promotion

Email provider mode:

  • current env contract expects EMAIL_PROVIDER=resend

R2 notes:

  • production should use a production-isolated bucket/config set
  • object-storage credentials must stay in secrets management only

Sentry environment value:

  • production

Important safety notes:

  • production startup must fail if JWT secrets still use development placeholders
  • do not test risky migrations or secret changes directly in production first
  • keep production deploys deliberate and traceable through the documented manual workflow

Cross-environment reminders​

Implemented:

  • the environment contract is shared across local and hosted contexts
  • GitHub Environments Staging and Production are part of the current deploy model

Partial:

  • Back Office hosted deployment steps are less explicit in repo automation docs than Manager Desk and API

Template-ready:

  • hosted URL inventory should eventually move from placeholders to an internal maintained links source once the team standardizes those addresses

Related docs: