Create a safe One Concept Staging app and environment #255

Goal

Create one safe Staging environment beside the existing Production environment. The staging app must install and run on the same phone as the production One Concept app without replacing it, sharing its account data, or receiving production updates.

Timing and current platform (2026-10-24)

Plan this work for the week of 2026-10-26, after the production Railway-to-Supabase migration is complete and verified. Keep this issue open; do not build or deploy the separate staging APK as part of the current cutover or PR #458.

The repository already identifies a separate Supabase staging project (zhrulokgngjceqgjkcmw) and production project (egdszjoesxlccauahmsx). Verify the staging project's live schema, API, Auth, workers, and access before reusing it; do not create a duplicate project by default. Supabase Edge Functions and Cron are the target for both environments. Earlier Railway staging requirements in this issue and its comments are superseded by this plan.

The existing Expo preview channel alone is not a staging environment. The last reviewed preview mobile values pointed at production Supabase. Before distributing the staging APK, configure and validate the preview EAS environment against staging-only Supabase URL, publishable key, API URL, Auth redirects, and test accounts. Leave production EAS variables unchanged.

This is a two-environment design:

A developer PC running Expo or FastAPI is only a temporary local test server. It is not a third deployed environment.

Problem in simple words

Today, the preview and production builds use the same Android package identity: com.codingmoves.oneconcept. Android treats two APKs with that identity as the same app. Installing a preview build can therefore replace the production app on a phone.

That makes PR testing risky. A tester should be able to open the real production app and the staging app side by side. The staging app also needs its own database, authentication users, backend URL, and update stream so test activity cannot touch real user data.

A production app must never be pointed at a PC's local server. It should continue to use only the production update channel and production services.

Required design

1. A separate One Concept Staging mobile app

Create a build variant with clear visual identity:

• Display name: One Concept Staging.
• Android package: com.codingmoves.oneconcept.staging.
• A distinct iOS bundle identifier and URL/deep-link scheme for future iOS support.
• A visibly different staging icon, label, or startup marker so a tester cannot mistake it for the production app.
• Production remains One Concept with com.codingmoves.oneconcept.
• Both APKs must install on one Android phone at the same time. Installing, updating, or deleting the staging app must not modify the production app.
• Publish a separate staging APK build link. Use the existing mobile source and EAS project; the distinct package identity, preview channel, and staging configuration create the separate installed app.

2. Separate cloud data and services

Create isolated staging resources:

• Verify and reuse the existing Supabase Staging project (zhrulokgngjceqgjkcmw), separate from production (egdszjoesxlccauahmsx); create a replacement only if the existing project fails the isolation/readiness checks.
• Deploy staging API and workers as Supabase Edge Functions from the reviewed develop revision, with staging-only Cron jobs and safe gates. Production API/workers remain on their protected Supabase deployment path from main.
• Staging database credentials, Supabase URL, Supabase publishable key, Edge API URL, Auth redirect URLs, and test-email settings must be separate from production values.
• Create test accounts only in staging. No production user data, database backups, service-role keys, Gemini keys, or SMTP credentials are copied into the app or committed to Git.
• Keep generation disabled in staging by default. Enable it only for a deliberate test with capped/non-production credentials.
• Configure staging Edge API health checks and Cron worker schedules safely. Reminder emails and notifications must not reach real users from staging.
• Register the staging Android package in Firebase/FCM with a matching google-services.json and EAS credentials before testing push reminders; do not reuse production push configuration by changing only the app label.

3. Separate update channels and configuration

Keep one EAS project but isolate update delivery by channel and environment:

• Production builds use the production channel and production EAS variables.
• Staging builds use the preview channel and staging EAS variables.
• A staging development-client build may use the staging package identity and the preview channel. It must be able to open a Metro bundle from a PC for a feature-branch test, then receive ordinary preview OTA updates when develop advances.
• Production phones must never receive preview updates. Staging phones must never receive production updates.
• Native changes require a new staging APK before staging testing, and a separate production build later. JavaScript-only changes can use OTA updates within the compatible runtime.
• Maintain the existing release rule: a release PR still needs a version bump and matching one-time What's New card. Do not publish a production OTA from a feature branch or from develop.

4. Local PR testing on a physical phone

Document a repeatable local flow:

1. Install One Concept Staging once on the Android phone.
2. Check out the feature branch on the PC.
3. Start FastAPI on 0.0.0.0:8000 using safe local/staging test configuration.
4. Set the feature branch's uncommitted local configuration to use the PC's LAN IP, such as http://192.168.x.x:8000; never use localhost on the phone.
5. Start Expo with npx expo start --dev-client --lan.
6. Connect the staging app to Metro and test the exact PR flow.
7. Run mobile typecheck/tests and backend tests before opening or updating the PR.
8. Stop Metro and the local backend when testing is finished. The production app remains unaffected throughout.

The phone and PC must be on the same Wi-Fi network. Document firewall guidance for port 8000 and how to find the PC LAN IP. Local environment files must remain gitignored.

5. Shared staging validation after merge

After a PR merges into develop:

• Deploy the Supabase Edge API and workers to the verified staging project.
• Run the existing preview OTA workflow against the preview channel.
• Test the merged behavior in One Concept Staging against staging Supabase only.
• Keep production untouched until a reviewed develop to main release PR is merged and the manual production Release workflow is run.

Do not publish an OTA for every open feature branch. A feature branch is tested locally through Metro; the shared staging app receives the integrated update after its PR merges into develop.

Implementation tasks

• Add a documented app-variant configuration for production and staging package names, display names, schemes, and visual marker.
• Add safe EAS build profiles for staging APK and staging development client; preserve the production profile.
• Configure EAS preview variables exclusively with staging public configuration and keep production variables unchanged.
• Verify the existing Supabase staging project's isolation, schema, API, Auth, redirect URLs/templates, test accounts, and safe worker defaults; create a replacement only if needed.
• Deploy staging Supabase Edge API and workers from develop; configure safe Cron schedules and generation switch.
• Register the staging package in Firebase/FCM and configure package-specific Android push credentials before notification tests.
• Add an explicit configuration validation that rejects production values in a staging build and rejects staging values in a production build.
• Update GitHub Actions so develop publishes only preview/staging updates after checks pass; main retains the guarded production release workflow.
• Add a local-phone test guide with exact commands, LAN troubleshooting, test-account rules, and rollback/reinstall instructions.
• Add automated checks for app variant identity, channel/environment pairing, and public configuration validation.
• Verify Android side-by-side installation: production stays signed in to production while staging signs in only to staging.
• Verify a staging OTA cannot reach production and a production OTA cannot reach staging.
• Verify sign-out, offline queue, password reset links, notifications, and account switching use the correct environment.

Acceptance criteria

• A tester can keep production One Concept installed while installing One Concept Staging.
• The two apps show different names and package identities and can be opened independently.
• Staging uses only staging Supabase API/Auth/data/workers, staging users, and preview updates.
• Production uses only production Supabase API/Auth/data/workers, production users, and production updates.
• A feature PR can be tested from a PC on a physical phone over LAN without modifying the production app or publishing an update.
• A merge to develop updates staging only after required checks pass.
• A production release remains the existing guarded develop to main process, including deployment verification, the manual Release workflow, and the matching What's New card.
• Setup and rollback are documented well enough for the owner to repeat without exposing secrets.

Out of scope

• Play Store submission and paid features.
• Moving production to a different provider.
• Restoring or copying production backups into staging.