Neon Postgres & Auth Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• lib/db/schema.ts
• lib/db/actions.ts
• app/page.tsx
• lib/db/client.ts (Inferred from context)

Vantage uses Neon as its serverless Postgres provider and Neon Auth (Managed Better Auth) for user authentication. This configuration provides the data persistence layer for workspaces, sources, documents, and leads, while ensuring secure access through managed identity services.

The system integrates Neon with Drizzle ORM for schema management and type-safe database interactions. Authentication state determines workspace access and allows users to create or join specific project environments.
Sources: README.md:8-11, package.json:28-31

Database Architecture

The database architecture leverages Neon's serverless capabilities. Vantage connects using a pooled DATABASE_URL to handle high-concurrency environments like Cloudflare Workers. Drizzle ORM defines the schema in TypeScript and handles migrations.
Sources: README.md:18-20, README.md:95-97

Core Tables and Relationships

The M1 milestone schema defines the primary data structures for multi-tenant workspace management.

This diagram illustrates the cascading relationships starting from the workspace tenant.
Sources: lib/db/schema.ts:100-200, drizzle/0000_m1_core.sql:7-50

Neon Auth Integration

Neon Auth (Managed Better Auth) handles user sessions and identity. The application uses the @neondatabase/auth and @neondatabase/auth-ui packages to facilitate sign-in and sign-up flows.
Sources: package.json:28-29

Authentication Flow

When a user accesses the root page, the application checks for an active session to redirect them to their workspace or the onboarding flow.

The flow ensures that only authenticated users can interact with workspace data.
Sources: app/page.tsx:21-30

Identity Mapping

The workspace table includes an owner_user_id field, which stores the unique ID provided by Neon Auth (neon_auth.user.id). This creates a link between the managed auth identity and the application's internal data model.
Sources: lib/db/schema.ts:107-108, lib/db/actions.ts:24-25

Environment Configuration

Correct configuration of environment variables is mandatory for the database and authentication systems to function.

Variable	Description	Requirement
DATABASE_URL	Neon pooled connection string	Required for DB access
NEON_AUTH_BASE_URL	The reachable URL for managed auth	Required for login/session
NEON_AUTH_COOKIE_SECRET	32-byte base64 string for session cookies	Required for session persistence

Sources: README.md:14-16, README.md:104-110

Connection Setup (Drizzle)

Vantage uses @neondatabase/serverless to connect. This driver is compatible with edge environments like Cloudflare Workers.
Sources: package.json:30, README.md:95-97

// Example from lib/db/actions.ts showing dependency on DB client
import { getDb } from "@/lib/db/client";

export async function createWorkspaceForCurrentUser(name: string) {
  // ... auth check ...
  const db = getDb(); // Initializes Neon serverless connection
  const [row] = await db.insert(workspace).values({
    name,
    ownerUserId: session.user.id,
    plan: "free",
  }).returning();
  return row;
}

Sources: lib/db/actions.ts:11-33

Deployment and Migrations

Migrations are managed manually via drizzle-kit to ensure production stability. The pipeline utilizes SQL files in the drizzle/ directory.

1. Generate: pnpm db:generate creates SQL snapshots from schema.ts.
2. Apply: pnpm db:migrate applies pending SQL to the target database.
3. Push: pnpm db:push pushes schema changes directly during development.

Sources: README.md:82-88, package.json:14-17

Deployment Context (Cloudflare)

Vantage runs as a Cloudflare Worker. Database secrets must be set via wrangler secret put before the first deployment to ensure the runtime can authenticate with Neon.
Sources: README.md:100-110

Neon Postgres and Auth provide the foundational infrastructure for Vantage. By combining serverless database pooling with managed authentication, the project maintains low overhead while supporting multi-tenant lead capture workflows.
Sources: README.md:3-6