docs: document Stack Auth deployment setup

[paccloud]

Summary

• add AUTH_ARCHITECTURE.md documenting the current JWT + Stack Auth + Neon architecture
• add Stack Auth env vars, Trusted Domains setup, and Vercel integration cleanup to DEPLOYMENT.md
• add troubleshooting for REDIRECT_URL_NOT_WHITELISTED and OAuth-only failures

Closes #14.

Verification

• npm run build in app/ passed
• npm run lint in app/ fails on existing React lint issues unrelated to this docs change, including unused vars and React hooks lint in existing source files
• root npm test -- --runInBand could not run because the root package has no test script

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
fish-cost-calculator	Ready	Preview, Comment	May 10, 2026 9:53pm

[coderabbitai]

Summary by CodeRabbit

• Documentation
  • Added comprehensive authentication architecture documentation covering system design and migration options.
  • Updated deployment guide with enhanced setup instructions, environment configuration steps, and troubleshooting guidance for cloud platform deployment.

Walkthrough

This PR adds comprehensive documentation for the project's dual authentication system. A new AUTH_ARCHITECTURE.md file documents the current password/JWT and OAuth/Stack Auth flows, data persistence requirements keyed to users.id, future authentication requirements, operational considerations, and five migration options with a consolidation checklist. DEPLOYMENT.md is updated to include Stack Auth environment variables, a new post-deployment configuration step for Trusted Domains and integration cleanup, revised deployment verification procedures, and Stack Auth–specific troubleshooting for OAuth redirect and login failures.

Changes

Authentication Architecture and Deployment Documentation

Layer / File(s)	Summary
Current Architecture AUTH_ARCHITECTURE.md	Introduces dual auth paths: password authentication (JWT + bcrypt) and OAuth (Stack Auth via Neon). Both map to the same users table via neon_auth_id and email.
Data Persistence & Migration Contract AUTH_ARCHITECTURE.md	User-owned data is keyed to users.id across tables. Future auth systems must support OAuth + email/password, cross-device identity persistence, req.user compatibility, and Neon/platform compatibility.
Operational Setup & Integration Management AUTH_ARCHITECTURE.md, DEPLOYMENT.md	Documents Stack Auth Trusted Domains requirements for OAuth redirects. Provides procedures to add production/preview domains, remove unused Clerk integration, and remove stale duplicate Neon integrations.
Migration Strategy & Checklist AUTH_ARCHITECTURE.md	Lists five auth options (Keep Stack Auth, Better Auth, Clerk, Auth.js, Supabase Auth) with trade-offs. Provides checklist for environment inventory, domain registration, integration cleanup, consolidation choice, mapping preservation, and end-to-end testing.
Deployment Environment Variables DEPLOYMENT.md	Updates Vercel env var table to include Stack Auth frontend/backend variables (VITE_STACK_PROJECT_ID, VITE_STACK_PUBLISHABLE_CLIENT_KEY, STACK_SECRET_SERVER_KEY).
Deployment Verification & Troubleshooting DEPLOYMENT.md	Restructures verification steps (Step 6 with new "Check API Logs" subsection). Adds Stack Auth–specific troubleshooting for REDIRECT_URL_NOT_WHITELISTED errors and OAuth-vs.-password login diagnosis.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• paccloud/Fish_Cost_Calculator#9: Earlier PR that also modifies Stack Auth environment variables and Vercel deployment configuration for the same Stack Auth + Neon integration.

Poem

🐰 Auth flows now charted,
Two paths through Neon bright,
JWT and OAuth danced,
Then docs made it right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: document Stack Auth deployment setup' clearly and concisely describes the main change in the PR: adding documentation for Stack Auth deployment configuration.
Description check	✅ Passed	The description is directly related to the changeset, detailing the addition of AUTH_ARCHITECTURE.md, updates to DEPLOYMENT.md with Stack Auth configuration, and troubleshooting additions.
Linked Issues check	✅ Passed	The PR addresses key coding-related requirements from issue #14: documenting Stack Auth architecture, adding deployment configuration, Vercel integration cleanup steps, and troubleshooting for REDIRECT_URL_NOT_WHITELISTED and OAuth failures.
Out of Scope Changes check	✅ Passed	All changes are within scope: documentation files only (AUTH_ARCHITECTURE.md and DEPLOYMENT.md updates) directly addressing issue #14 requirements without unrelated code modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-14-auth-docs

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

DEPLOYMENT.md (1)

109-112: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify preview env vars are required when validating OAuth on preview deployments.

Marking preview variables as merely optional can cause avoidable OAuth failures in preview. Recommend stating they are required if preview auth testing is part of verification.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@DEPLOYMENT.md` around lines 109 - 112, Update the third step that currently
says "Optionally add for 'Preview' environments too" to clarify that preview
environment variables must be added when you need to validate OAuth on preview
deployments; specifically change the text to indicate: Add each variable for the
"Preview" environment as well when you plan to test or validate OAuth on preview
deployments (required for preview auth testing), and include a short note to
ensure preview-specific OAuth redirect URIs/credentials match the preview
deployment.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@DEPLOYMENT.md`:
- Around line 109-112: Update the third step that currently says "Optionally add
for 'Preview' environments too" to clarify that preview environment variables
must be added when you need to validate OAuth on preview deployments;
specifically change the text to indicate: Add each variable for the "Preview"
environment as well when you plan to test or validate OAuth on preview
deployments (required for preview auth testing), and include a short note to
ensure preview-specific OAuth redirect URIs/credentials match the preview
deployment.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cb329583-961e-4e0a-93a7-b4f9a9c5e8c3

📥 Commits

Reviewing files that changed from the base of the PR and between 6fe2dbf and 0adcfe5.

📒 Files selected for processing (2)

• AUTH_ARCHITECTURE.md
• DEPLOYMENT.md