docs(architecture): reframe architecture-overview as backend-first (worked example) [DRAFT]

[bgrenon]

Proof of concept: backend-first docs reframe

For two years, Neon docs have framed the product as "serverless Postgres" with features orbiting the database. The proposed reframe: Neon is a full-service application backend, of which serverless Postgres is the foundation.

This PR reworks a single page, content/docs/introduction/architecture-overview.md, as a worked example to see whether that reframe holds up in a real diff before applying it more broadly. This page was picked because it's the deepest and most database-only page in the docs: it explained the whole architecture purely as Postgres storage/compute separation and never brought Auth, Object Storage, Functions, or the AI Gateway into the mental model.

What changed

• Kept all existing technical detail on the compute/storage split, safekeepers, the pageserver, the write path, the read path, and durability. That material was already strong and didn't need rewriting, just recontextualizing.
• Added a new A foundation for more than Postgres section (right after the existing Neon/Lakebase distinction admonition) that explains how Neon Object Storage, Neon Functions, and Managed Better Auth each attach to and fork with a branch, using the same substrate (durable state outside the compute node) that makes Postgres branching possible.
• Added a note to the Resource hierarchy table clarifying that Object Storage buckets and Function deployments attach at the Branch level without new hierarchy levels, and that Auth adds no new resource since its state lives inside a Database that already belongs to the Branch.
• Added a A branchable backend, not just a branchable database bullet to What this architecture enables, stating plainly what does and doesn't fork with a branch.
• Updated the closing In short paragraph and the subtitle/summary frontmatter to carry the same framing.
• Title kept as "The lakebase architecture" (established brand term used across dozens of other docs/blog posts that link here) — only the subtitle and summary changed.

Accuracy constraints honored

These were given as hard, pre-verified constraints for this rewrite. A reviewer should check each:

1. The AI Gateway does not branch. The page explicitly states AI Gateway credentials are scoped to the Neon account, not to a branch, and that a new branch does not get its own gateway. This is called out twice: once in the new "foundation" section and once in the "branchable backend" bullet.
2. Object Storage and Functions branching is flag-gated, not GA. Both the new section and the "branchable backend" bullet note this is "rolling out behind a per-organization flag," with a single Admonition callout rather than scattering hedges through the page.
3. Managed Better Auth branches because its tables live inside the branch's own Postgres (the neon_auth schema), not because it's a separate branch-aware system. The page frames it exactly this way: "doesn't add a separate branch-aware system at all... branches for free whenever Postgres does."
4. Restore stays Postgres-scoped. The existing "Instant restores" bullet was left untouched; no claim was added or implied about backend-wide (storage/functions) point-in-time consistency.

Note on an existing inconsistency (not touched here, out of scope)

While reading introduction/branching.md and ai-gateway/overview.md for voice/consistency, I found both currently say the AI Gateway does branch (branching.md: "Object Storage, Functions, and AI Gateway all branch with your data too... isolated gateway endpoint"; ai-gateway/overview.md summary: "Each branch gets its own gateway endpoint."). That contradicts the verified constraint given for this task. I did not change those pages since they're out of scope for this PR, but they likely need a correction pass if the AI Gateway's account-scoping is confirmed correct.

Checks run

• npx prettier --check on the touched file: clean
• npx markdownlint --ignore-path .gitignore on the touched file: clean
• npx vitest run scripts/docs-checks/**/__tests__/*.test.js (docs-specific checks): 47/47 passed
• npm run test:unit:run (full unit suite, same as the pre-push hook): 677/677 passed
• Verified every internal doc link added (/docs/storage/overview, /docs/compute/functions/overview, /docs/auth/overview, /docs/ai-gateway/overview, /docs/get-started/backend-overview, etc.) resolves to a real file
• Verified the two heading anchors referenced by other docs/blog posts (#storage-layer, #what-this-architecture-enables) are unchanged so existing external links don't break

This pull request and its description were written by Isaac.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
neon-next	Ready	Preview	Aug 5, 2026 7:27pm