Status: Proposed
Date: 2026-04-29 UTC
Refs: docs/architecture/prod-deploy-gating.md, docs/architecture/console-env-switcher.md, #81, #353
Both the API (Raptor) and the console have historically had staging and production Heroku apps. The two systems are now diverging in their staging model:
Raptor (raxx-api-staging + raxx-api-prod): retains two Heroku apps. main auto-deploys to staging; prod requires manual dispatch or tag-gate approval. Staging is a live environment that receives every commit and can be used as an integration target.
Console (raxx-console-staging → retired, raxx-console-prod): retires the staging Heroku app in favor of an in-app environment switcher. The single console.raxx.app deployment targets either prod or staging infrastructure via a dropdown + colored banner.
This ADR records why the two systems make different choices.
Retire raxx-console-staging and keep raxx-api-staging.
Why the console retires its staging app:
The console's "staging" is not a separate codebase deployment — it is a routing key. The console targets either prod Raptor or staging Raptor for its API calls; the console application code is identical in both cases. Running two separate console Heroku apps to point at two different Raptor backends is wasteful: it doubles the dyno cost, the deploy surface, and the configuration drift risk.
The env-switcher replaces the staging app's purpose. The raxx-console-staging Heroku app existed so operators could test the console against staging infrastructure without touching prod. The env-switcher (designed in #353, implemented in sub-cards) provides that same capability from a single deployment with better UX: a colored banner makes the active environment unambiguous, and the session-level env context is logged in the audit trail.
Single deployment reduces deploy surface. With raxx-console-staging retired, there is one console deployment to gate, one console health check to monitor, and one console deployment to roll back. Fewer surfaces means fewer failure modes.
Staging retirement is gated on env-switcher stability. The raxx-console-staging app is not destroyed until the env-switcher has soaked for at least one week in production (≥ 2026-05-07). If the env-switcher develops critical bugs during that window, staging still exists as a fallback. See console/docs/ops-runbook.md#retiring-raxx-console-staging for the pre-teardown checklist.
Why the API keeps its staging app:
Raptor staging runs live code against live infrastructure (databases, broker sandbox, Infisical staging path). It is genuinely a separate deployment with a separate database. Collapsing Raptor to a single production deployment with a routing key is not viable — the databases are separate Postgres instances, not an env flag.
Raptor staging receives every main push automatically. It is the soak environment for features before they go to prod. Removing it would mean prod receives every merge directly, which contradicts the soak gate model in ADR-0020.
Raptor staging is needed as a health-check target during console env-switch. When a console operator switches to env=staging, the console calls Raptor staging endpoints. raxx-api-staging must remain live for this to work.
Keep both console apps indefinitely
Doubles the console deployment surface. Every console change requires two deploys. Config drift between the two apps becomes a maintenance burden. The env-switcher already provides the staging-targeting capability. No benefit over the single-deployment model.
Retire Raptor staging and apply the same env-switcher model to Raptor
Not viable. Raptor staging has a separate Postgres database, separate Infisical secret paths, and separate Alpaca paper-trading credentials. An env-switcher flag cannot substitute for a live staging database. Raptor staging serves a fundamentally different purpose than console staging.
Keep console staging for CI smoke targets
deploy-console.yml can run its staging smoke check against raxx-console-prod (after a staging-targeted deploy job) or against a review-app pattern. The console staging Heroku app is not required as a CI smoke target; the deploy workflow can target prod-staging-like behavior via the env-switcher without a separate Heroku app.