Staging and Production Promotion

All TrickBook web and backend features follow this path:

feature/* → pull request to staging → automated checks → staging deploy → manual QA → pull request from staging to production

Production branches are main for the website and master for the backend. The promotion check rejects production pull requests whose source branch is not staging.

Environment isolation

Concern	Staging	Production
Web	Amplify staging branch	Amplify main branch
API	Separate EC2 worktree/process/port	Existing EC2 production process
MongoDB	Separate database selected with MONGODB_DATABASE	TrickList2
Neo4j	Staging graph/database	Production graph/database after readiness review
Secrets	Branch/process environment	Production environment

Never copy production secrets into source control or expose them in build logs. Test data may be seeded from sanitized public fields, not by cloning credentials, tokens, messages, or private account fields.

Current parity gap (September 3, 2026)

The first staging slice proves branch isolation and the Riders API, but it is not yet a production-parity environment. The staging database intentionally began empty and currently contains only sanitized Rider fixtures. Most application pages therefore appear empty, and authentication providers have not been configured with staging callback URLs. Treat staging as feature-limited until every gate below is complete.

Production-parity plan

Phase 1: environment contract and safety rails

Create one versioned environment-variable manifest containing variable names, owners, consumers, and whether each value is shared or isolated. Values remain in AWS/EC2 secret storage, never in Git. The staging configuration must explicitly set:

• NEXTAUTH_URL and FRONTEND_URL to the staging web origin;
• NEXT_PUBLIC_API_BASE_URL, Socket.IO, and Kith WebSocket URLs to staging routes;
• a staging-only MONGODB_DATABASE and staging CORS origins;
• environment-scoped JWT/session secrets;
• safe Stripe, email, push, S3, Bunny, analytics, and AI settings.

The backend must expose an environment marker through its health response, and the frontend must show a persistent STAGING banner. Any staging process that resolves the production database name must refuse to boot.

Phase 2: authentication parity

Register staging as an authorized web origin and callback/redirect URI in both provider consoles.

Google: Prefer a separate OAuth client named TrickBook Web Staging. Add the exact staging origin and https://<staging-host>/api/auth/callback/google. Configure the backend's staging Google audience explicitly when backend token exchange is used.

Apple: Add https://<staging-host>/api/auth/callback/apple to the Services ID configuration, or use a dedicated staging Services ID if required. Keep the private key only in protected environment configuration.

Sessions and credentials: Use staging-specific NEXTAUTH_SECRET and backend JWT_SECRET values so production sessions cannot be replayed. Validate secure cookies, SameSite, callback URLs, logout, provider-mismatch recovery, and Forgot Password. Create designated staging test accounts; never authenticate staging against production user documents.

Phase 3: representative sanitized data

Build a repeatable, idempotent refresh job from production to staging. It must use collection-specific allowlists and transformations rather than copying the database.

• Copy public/reference content needed for realistic browsing: categories, Trickipedia, approved spots, events, public Couch catalog metadata, and approved editorial Riders.
• Create synthetic member identities for authenticated flows. Public member cards may be copied only from opted-in public fields.
• Preserve relationship shape with remapped staging IDs when testing Homies, messages, lists, claims, and ownership.
• Never copy password hashes, OAuth subject IDs, reset tokens, JWTs, email addresses, private messages, push tokens, billing identifiers, precise private locations, private lists, or companion memory.
• Media records may reference production read-only CDN assets for display testing; staging uploads must use isolated storage/library prefixes.
• Record refresh version, source snapshot time, transformed counts, exclusions, and verification results.

Phase 4: service parity without production side effects

Service	Staging policy
MongoDB	Separate database; guarded startup and importer checks
S3/images	Separate bucket or mandatory staging/ prefix with restricted IAM
Bunny/Couch	Production catalog may be read-only; uploads use a staging library
Stripe	Test-mode keys, products, prices, and webhook endpoint only
Email	Capture/sink provider or strict allowlist; never send to copied addresses
Push notifications	Disabled by default or limited to registered staging devices
Socket.IO/Kith	Dedicated staging paths/processes and explicit frontend URLs
PostHog/Sentry/logging	Separate project/environment tags and no production user PII
AI providers	Separate budgets, rate limits, and staging telemetry
Neo4j	Separate database/instance built only from staging Mongo projections

Phase 5: deployment automation

• Amplify automatically deploys staging; main remains production.
• EC2 deployment updates /home/ubuntu/TB-Backend-staging, installs from the lockfile, runs checks, restarts only TB-Backend-staging, and verifies health.
• Failed staging deployments retain the previous healthy revision for rollback.
• Database migrations and indexes run against staging first and are idempotent.
• Production promotion remains a PR from staging only and requires a recorded staging revision plus QA result.

Phase 6: parity test suite

Automate browser/API tests for:

1. anonymous navigation and public data pages;
2. email/password registration, login, logout, reset, and session persistence;
3. Google and Apple SSO, including provider-mismatch recovery;
4. profile editing, Riders/Homies, messages, lists, media, Couch, spots, events, and claims;
5. upload/playback using staging storage;
6. pagination, search, filters, responsive layout, images, WebSockets, and error states;
7. zero browser console errors, failed first-party requests, or unexpected production writes.

Parity readiness gate

Staging is production-like only when both SSO providers pass end to end; the sanitized refresh supplies every core surface; all external services are isolated or explicitly read-only; authenticated and anonymous browser suites pass; telemetry identifies staging; and a destructive-write canary proves staging cannot mutate production data, storage, billing, email, or push systems.

Required QA before promotion

1. CI passes in both repositories.
2. Staging health and API smoke checks pass.
3. Anonymous and authenticated browser paths pass.
4. Data mutations are confirmed against the staging database.
5. Error and process logs are clean during the test run.
6. A human approves the staging → production PR.

Emergency production fixes require an explicit incident note and must be merged back into staging immediately after production recovery.