Add branch deploy restoration strategy document

[marcodejongh]

Summary

• Adds docs/branch-deploys.md — a comprehensive, actionable plan to restore branch deploys across the full stack (Vercel, Railway, Neon)
• Covers four independently valuable phases: frontend-only previews, full-stack branch deploys, API consolidation, and sync migration
• Includes decision matrix, cost analysis, risks/mitigations, and key file references grounded in the current codebase

Phases

1. Phase 1: Quick Win (~1-2 days) — Re-enable migrations on preview, set NEXT_PUBLIC_WS_URL for preview scope, add change detection workflow
2. Phase 2: Full-Stack (~3-5 days) — Neon API branching (with Railway fallback), Railway backend environments, runtime backendUrl override, cleanup on PR close
3. Phase 3: API Consolidation (~2-4 weeks) — Migrate 28 Next.js API routes to backend GraphQL (reads → mutations → proxies)
4. Phase 4: Sync Migration (~1-2 weeks) — Centralize sync on backend, remove Vercel crons

Test plan

• Review document for accuracy against current codebase
• Verify referenced files and code patterns are correct
• Confirm phases are independently valuable and ordering makes sense

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
boardsesh	Error		Feb 24, 2026 4:06pm

[claude]

Claude Review

✅ Ready to merge - Minor issue noted below, but nothing blocking.

---

vercel.json migration risk not yet mitigated: The PR removes the preview migration skip (line 4), which the documentation correctly identifies as risky for destructive migrations (DROP, column renames). The doc proposes a CI check to flag such migrations (Section 1.1, "Risks & Mitigations"), but that safeguard is not implemented in this PR. Consider adding the migration safety workflow before or alongside this change.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 21e5ff53cb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep preview migrations off the production database

The proposed buildCommand runs npm run db:migrate on every preview deployment, which means unmerged PR code can apply schema changes to production before review/merge. This is a production-safety regression even if migrations are usually additive, because preview builds execute on each push and can include destructive or incompatible SQL from feature branches.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Expand shell variables in Neon branch creation example

This curl example wraps the JSON payload in single quotes, so ${PR_NUMBER} and ${MAIN_BRANCH_ID} are sent literally instead of being expanded by the shell. If copied as written, the branch creation request will use placeholder strings and fail or create incorrectly named resources, blocking the Phase 2 setup flow.

Useful? React with 👍 / 👎.