Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Vantage is a social listening and lead capture platform built as an M1 scaffold. It identifies high-intent conversations across platforms like Reddit, Hacker News, and X to provide ranked opportunities for user interaction.
The setup process involves configuring a Next.js environment with a Neon Postgres database, Drizzle ORM, and Neon Auth. This documentation covers the technical requirements, environment configuration, and initial database deployment necessary to run the project locally.
Sources: README.md:1-5, app/page.tsx:32-36
Technical Stack
Vantage utilizes a modern web stack optimized for serverless deployment on Cloudflare Workers via OpenNext.
| Component | Technology |
|---|---|
| Framework | Next.js (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS |
| Database | Neon Postgres |
| ORM | Drizzle ORM |
| Auth | Neon Auth (Managed Better Auth) |
| Runtime | Node.js (>=22) |
Sources: README.md:7-12, package.json:5-10
Local Environment Setup
Follow these steps to initialize the Vantage repository on a local machine.
1. Install Dependencies
Vantage uses pnpm for package management. Ensure Node.js version 22 or higher is installed.
pnpm install
Sources: README.md:14-16, package.json:5-7
2. Configure Environment Variables
Create a local environment file by copying the template.
cp .env.example .env.local
You must populate .env.local with specific secrets and connection strings.
- DATABASE_URL: The pooled connection string from your Neon project.
- NEON_AUTH_BASE_URL: The Managed Better Auth URL provided by Neon.
- NEON_AUTH_COOKIE_SECRET: A 32-character base64 string. Generate it using:
openssl rand -base64 32
Sources: README.md:17-27
3. Initialize the Database
Vantage uses Drizzle Kit to manage migrations. Apply the initial schema to your Neon database instance.
pnpm db:migrate
This command executes the core SQL definitions found in drizzle/0000_m1_core.sql.
Sources: README.md:19-20, package.json:20
Database Architecture
The M1 schema defines the core entities required for lead capture and workspace management.
Entity Relationship Diagram
The following diagram illustrates the relationships between the primary tables in the Vantage system.
The schema centers around the workspace as a tenant, with source configurations defining how content is collected into the document table before being processed into lead records.
Sources: README.md:31-38, lib/db/schema.ts:108-185, drizzle/0000_m1_core.sql:5-55
Development Workflow
Once configured, use the following commands to manage the local development lifecycle.
| Script | Command | Action |
|---|---|---|
| Start Dev Server | pnpm dev | Runs the Next.js development server. |
| Database Studio | pnpm db:studio | Opens the Drizzle Kit GUI for database exploration. |
| Schema Push | pnpm db:push | Syncs schema changes to the database (development only). |
| Type Checking | pnpm typecheck | Executes tsc --noEmit. |
| Run Tests | pnpm test | Executes the Vitest suite. |
Sources: README.md:75-86, package.json:15-24
Project Initialization Flow
The following sequence describes the application logic when a user first accesses the local instance.
Initial access requires creating a workspace and a monitoring profile. If these do not exist, the application redirects the user to the onboarding flow.
Sources: app/page.tsx:13-30
Summary
Setting up Vantage locally requires a Neon Postgres project with Managed Better Auth enabled. After configuring the environment variables and running migrations, developers can use pnpm dev to start the Next.js application. The system is built around a multi-tenant workspace architecture that facilitates the collection and scoring of social leads.