docs: add ADR 003 - deployment architecture for MVP#5
Merged
Conversation
Captures the Phase 8 architecture decisions so execution can be mechanical rather than design-on-the-fly. Decisions - Hosting: split web + API on Railway, subdomain routing (stackfast.app + api.stackfast.app). Railway CLI is how the operator already interacts with the account. - Database: existing Neon Postgres, separate production and staging branches; Drizzle migrations forward-only in prod. - Rate limiting: Upstash Redis via @upstash/ratelimit, replacing the in-memory Map flagged as TODO in apps/api/src/index.ts. Fails open on Redis outage. - Auth cookies: cross-origin with SameSite=None + Secure, cookie domain .stackfast.app so API and web share sessions. - Error tracking: Sentry is the choice if enabled; treated as nice-to-have rather than a hard MVP requirement. - Secrets: Railway env vars only, documented in .env.example. - Rollback: Railway one-click for web, two-phase schema migrations so any deploy can roll back without DDL surgery. Also adds a Phase-8 task outline the spec will expand on. Roadmap - Corrects the Phase 8 auth line to reference Better Auth + GitHub OAuth (per ADR 001), not "Neon Auth via Neon Console". - Adds the Upstash rate-limit migration to the deliverable checklist. - Links to ADR 003 at the top of Phase 8. No code or config changes. Phase 8 execution and the Phase 8 spec follow in separate PRs.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="ROADMAP.md">
<violation number="1" location="ROADMAP.md:252">
P2: This deliverable omits staging branch provisioning, which conflicts with ADR 003’s required production + staging Neon branch setup.</violation>
</file>
<file name="docs/decisions/003-deployment-architecture.md">
<violation number="1" location="docs/decisions/003-deployment-architecture.md:21">
P2: This ADR changes Phase 8 auth to Better Auth, but phase-gate docs still require Neon Auth. Update the gate docs to keep deployment requirements consistent.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| - [ ] Neon Postgres provisioned and connected | ||
| - [ ] Neon Auth configured with GitHub OAuth via Neon Console | ||
| - [ ] Web + API deployed to Railway (via Railway CLI) | ||
| - [ ] Neon Postgres production branch provisioned and connected |
There was a problem hiding this comment.
P2: This deliverable omits staging branch provisioning, which conflicts with ADR 003’s required production + staging Neon branch setup.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At ROADMAP.md, line 252:
<comment>This deliverable omits staging branch provisioning, which conflicts with ADR 003’s required production + staging Neon branch setup.</comment>
<file context>
@@ -242,15 +242,21 @@ Build a registry that's genuinely useful for 2026 technology decisions.
-- [ ] Neon Postgres provisioned and connected
-- [ ] Neon Auth configured with GitHub OAuth via Neon Console
+- [ ] Web + API deployed to Railway (via Railway CLI)
+- [ ] Neon Postgres production branch provisioned and connected
+- [ ] Better Auth + GitHub OAuth configured (ADR 001)
+- [ ] Upstash Redis provisioned, rate limiter migrated off in-memory `Map`
</file context>
Suggested change
| - [ ] Neon Postgres production branch provisioned and connected | |
| - [ ] Neon Postgres production + staging branches provisioned and connected |
| + React 18), six shared packages. | ||
| - **Database:** Neon Postgres. See ADR 001 — auth data lives in our own | ||
| Postgres via Better Auth. | ||
| - **Auth:** Better Auth with GitHub OAuth (ADR 001). Cookies are |
There was a problem hiding this comment.
P2: This ADR changes Phase 8 auth to Better Auth, but phase-gate docs still require Neon Auth. Update the gate docs to keep deployment requirements consistent.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/decisions/003-deployment-architecture.md, line 21:
<comment>This ADR changes Phase 8 auth to Better Auth, but phase-gate docs still require Neon Auth. Update the gate docs to keep deployment requirements consistent.</comment>
<file context>
@@ -0,0 +1,257 @@
+ + React 18), six shared packages.
+- **Database:** Neon Postgres. See ADR 001 — auth data lives in our own
+ Postgres via Better Auth.
+- **Auth:** Better Auth with GitHub OAuth (ADR 001). Cookies are
+ `SameSite=Lax` by default; cross-origin cookies require `Secure` +
+ `SameSite=None` and matching `allowedOrigins`.
</file context>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures the Phase 8 architecture decisions so execution can be mechanical rather than design-on-the-fly.
Decisions
stackfast.app+api.stackfast.app)@upstash/ratelimit, replacing the in-memoryMapflagged as TODO inapps/api/src/index.ts. Fails open on Redis outageSameSite=None; Secure, cookie domain.stackfast.appso API and web share sessionsSENTRY_DSNfeature flag so it's a no-op if the DSN is missing.env.examplelists every variable that exists in any environmentRoadmap updates
SENTRY_DSNfeature flag"Non-goals (deferred to v1.x)
Out of scope for this PR
Summary by cubic
Adds ADR 003 that defines the MVP deployment architecture and updates the Phase 8 roadmap to link and align. ADR sets split Railway web/API with subdomains (
stackfast.app/api.stackfast.app), Neon Postgres branches with forward-only Drizzle migrations, Upstash Redis rate limiting via@upstash/ratelimit(fail-open), cross-origin cookies (SameSite=None; Secure, domain.stackfast.app), Sentry behindSENTRY_DSN, Railway env vars, and a rollback plan.Written for commit f62db37. Summary will update on new commits.