Installation

This guide walks you through setting up DelightBridge from scratch, including database setup, Google OAuth configuration, environment variables, and deployment options.

Prerequisites

Before you begin, ensure you have:

Node.js 20+ and pnpm installed
A Neon DB account (or any PostgreSQL database)
A Google Cloud Platform project with OAuth credentials
An Anthropic API key
(Optional) A Vercel account for deployment

Step 1: Clone and install dependencies

Clone the repository

git clone https://github.com/your-org/delightbridge.git
cd delightbridge

Install dependencies

DelightBridge uses pnpm as the package manager:

pnpm install

Step 2: Set up the database

DelightBridge uses Neon DB (serverless PostgreSQL) with Drizzle ORM.

Create a Neon DB project

Go to console.neon.tech
Click “New Project”
Choose a region close to your users
Copy the connection string (starts with postgresql://)

Add DATABASE_URL to environment

Create a .env.local file in the project root:

.env.local

DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require

Keep this file secret! Add .env.local to .gitignore (already included by default).

Push the database schema

Drizzle will create all tables automatically:

pnpm db:push

This creates the following tables:

users — Workspace members with authentication info
workspace_members — Email allowlist for login
gmail_accounts — Services (Gmail accounts) with OAuth tokens
categories — Service-specific email categories
email_threads — Email conversations
emails — Individual messages within threads
drafts — AI-generated reply drafts

You can view and edit your database using Drizzle Studio:

pnpm db:studio

This opens a web UI at https://local.drizzle.studio.

Step 3: Configure Google OAuth

DelightBridge uses Google OAuth for two purposes:

App authentication (NextAuth): Who can log in to the workspace
Service Gmail connection: Which Gmail accounts to sync

Create OAuth credentials

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to APIs & Services > Credentials
Click “Create Credentials” > “OAuth 2.0 Client ID”
Choose “Web application”

Configure authorized redirect URIs

Add the following redirect URIs:For local development:

http://localhost:3000/api/auth/callback/google
http://localhost:3000/api/services/oauth/callback

For production (replace with your domain):

https://your-app.vercel.app/api/auth/callback/google
https://your-app.vercel.app/api/services/oauth/callback

Enable Gmail API

In Google Cloud Console, go to APIs & Services > Library
Search for “Gmail API”
Click “Enable”

Copy credentials to environment

After creating OAuth credentials, copy the Client ID and Client Secret:

.env.local

GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

Make sure your OAuth consent screen is configured. During development, you can use “Testing” mode and add test users manually.

Step 4: Configure NextAuth

NextAuth handles user authentication and sessions.

Generate AUTH_SECRET

Generate a random secret for session encryption:

openssl rand -base64 32

Add it to .env.local:

.env.local

AUTH_SECRET=your-generated-secret-here

Set admin emails

Define who has admin access (comma-separated list):

.env.local

ADMIN_EMAILS=[email protected],[email protected]

Users in ADMIN_EMAILS can always log in and have full Admin permissions. Other users must be added via the “권한 관리” (Permissions) tab in Settings.

Step 5: Configure Anthropic API

DelightBridge uses Claude Sonnet 4 for draft generation.

Get an Anthropic API key

Go to console.anthropic.com
Sign up or log in
Navigate to API Keys
Click “Create Key”
Copy the key (starts with sk-ant-)

Add to environment

.env.local

ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Anthropic API has rate limits. For high-volume usage, consider requesting a rate limit increase or implementing request queuing.

Step 6: Configure Vercel Cron (optional)

For automatic Gmail sync every 5 minutes, set up Vercel Cron.

Generate a cron secret

openssl rand -base64 32

Add to .env.local:

.env.local

CRON_SECRET=your-cron-secret-here
CRON_SYNC_MAX_ACCOUNTS=20

CRON_SYNC_MAX_ACCOUNTS limits how many services are synced per cron run (prevents timeout).

Verify vercel.json configuration

DelightBridge includes a vercel.json file with cron configuration:

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/sync-gmail",
      "schedule": "*/5 * * * *"
    }
  ]
}

This runs incremental Gmail sync every 5 minutes.

Step 7: Complete environment configuration

Your final .env.local should include all of these variables:

.env.local

# Database
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require

# Google OAuth
GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

# NextAuth
AUTH_SECRET=your-generated-secret-here
ADMIN_EMAILS=[email protected],[email protected]

# AI
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# Cron (optional, for Vercel deployment)
CRON_SECRET=your-cron-secret-here
CRON_SYNC_MAX_ACCOUNTS=20

Never commit .env.local to version control. Use environment variables in your deployment platform (Vercel, Railway, etc.).

Step 8: Run locally

Start the development server

pnpm dev

DelightBridge will start at http://localhost:3000.

Verify the setup

Open http://localhost:3000 in your browser
You should be redirected to /login
Click “Google로 로그인” and authenticate
After login, you should see the main interface (or a “No services” prompt)

Step 9: Deploy to Vercel (optional)

Install Vercel CLI

pnpm add -g vercel

Deploy

vercel

Follow the prompts to link your project.

Add environment variables

In the Vercel dashboard:

Go to Settings > Environment Variables
Add all variables from .env.local
Make sure to add them for Production, Preview, and Development environments

Update OAuth redirect URIs

Go back to Google Cloud Console and add your Vercel domain to the authorized redirect URIs:

https://your-app.vercel.app/api/auth/callback/google
https://your-app.vercel.app/api/services/oauth/callback

Deploy to production

vercel --prod

Step 10: Seed initial data (optional)

For testing, you can seed the database with sample data:

pnpm db:seed

This creates:

Sample services (Noji, AnkiPro)
Categories for each service
Mock email threads

Only run this in development! It will create mock data in your database.

Database schema reference

Here’s an overview of the database tables:

`users`

Stores authenticated workspace members.

Column	Type	Description
`id`	text	Primary key (e.g., `user-123`)
`googleId`	text	Google OAuth sub (unique)
`email`	text	User email (unique)
`name`	text	Display name
`picture`	text	Profile picture URL
`permission`	enum	`view`, `edit`, `send`, or `admin`
`createdAt`	timestamp	Account creation time

`workspace_members`

Email allowlist for login (invite-only).

Column	Type	Description
`email`	text	Primary key
`permission`	enum	Default permission level
`createdAt`	timestamp	When added

`gmail_accounts`

Services (Gmail accounts).

Column	Type	Description
`id`	text	Primary key (e.g., `service-123`)
`name`	text	Service name (e.g., “Noji”)
`email`	text	Connected Gmail address
`color`	text	Brand color (hex)
`signature`	text	HTML email signature
`document`	text	Reference docs (Markdown)
`accessToken`	text	OAuth access token
`refreshToken`	text	OAuth refresh token
`lastHistoryId`	text	Gmail sync cursor
`createdAt`	timestamp	Service creation time

`categories`

Service-specific email categories.

Column	Type	Description
`id`	text	Primary key
`accountId`	text	Foreign key to `gmail_accounts`
`name`	text	Category name
`color`	text	Background color (hex)
`textColor`	text	Text color (hex)

`email_threads`

Email conversations.

Column	Type	Description
`id`	text	Primary key
`accountId`	text	Foreign key to `gmail_accounts`
`gmailThreadId`	text	Gmail thread ID
`subject`	text	Email subject
`customerEmail`	text	Customer email address
`customerName`	text	Customer name
`categoryId`	text	Auto-assigned category
`status`	enum	`inbox`, `sent`, or `archived`
`detectedLanguage`	text	Language code (e.g., `en`)
`isRead`	boolean	Read status
`lastMessageAt`	timestamp	Last message time
`createdAt`	timestamp	Thread creation time

`emails`

Individual messages within threads.

Column	Type	Description
`id`	text	Primary key
`threadId`	text	Foreign key to `email_threads`
`gmailMessageId`	text	Gmail message ID
`fromEmail`	text	Sender email
`fromName`	text	Sender name
`toEmail`	text	Recipient email
`body`	text	HTML body
`direction`	enum	`inbound` or `outbound`
`sentAt`	timestamp	Message timestamp
`createdAt`	timestamp	DB creation time

`drafts`

AI-generated reply drafts.

Column	Type	Description
`id`	text	Primary key
`threadId`	text	Foreign key to `email_threads` (unique)
`subject`	text	Reply subject
`content`	text	HTML body
`translation`	text	Korean translation
`status`	enum	`pending`, `ready`, `sent`, or `skipped`
`sentAt`	timestamp	When sent
`updatedAt`	timestamp	Last edit time

Project structure

delightbridge/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/                # API routes
│   │   │   ├── auth/           # NextAuth handlers
│   │   │   ├── cron/           # Vercel cron endpoints
│   │   │   ├── draft/          # AI draft generation
│   │   │   ├── members/        # Workspace member management
│   │   │   ├── services/       # Service CRUD + OAuth
│   │   │   └── threads/        # Email thread CRUD + send
│   │   ├── login/              # Login page
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Main app page
│   ├── components/             # React components
│   │   ├── MainLayout.tsx      # App orchestrator
│   │   ├── Sidebar.tsx         # Service switcher
│   │   ├── MailList.tsx        # Thread list
│   │   ├── MailDetail.tsx      # Thread detail panel
│   │   ├── ThreadView.tsx      # Email thread display
│   │   ├── DraftEditor.tsx     # TipTap editor
│   │   ├── TalkToDraft.tsx     # Natural language refinement
│   │   ├── TranslationPanel.tsx# Korean translation
│   │   ├── SendConfirmModal.tsx# Send confirmation
│   │   ├── BulkSendModal.tsx   # Bulk send confirmation
│   │   └── SettingsModal.tsx   # Settings UI
│   └── lib/
│       ├── db/                 # Database
│       │   └── schema.ts       # Drizzle schema
│       ├── types.ts            # TypeScript types
│       ├── utils.ts            # Utilities
│       ├── gmail.ts            # Gmail API helpers
│       ├── gmail-sync.ts       # Gmail sync logic
│       ├── session.ts          # NextAuth session guards
│       └── admin-emails.ts     # Admin email list
├── auth.ts                     # NextAuth config
├── auth.config.ts              # NextAuth Edge config
├── proxy.ts                    # Auth middleware
├── drizzle.config.ts           # Drizzle config
├── package.json                # Dependencies
├── vercel.json                 # Vercel cron config
└── .env.local                  # Environment variables (gitignored)

Available commands

pnpm dev          # Start development server (http://localhost:3000)
pnpm build        # Build for production
pnpm start        # Start production server
pnpm lint         # Run ESLint
pnpm db:push      # Push Drizzle schema to database
pnpm db:studio    # Open Drizzle Studio (database UI)
pnpm db:seed      # Seed database with mock data (dev only)

Next steps

Quickstart

Follow the quickstart guide to connect your first service and generate a draft

Team Collaboration

Add team members and configure permissions

Gmail Integration

Learn about automatic sync, manual triggers, and troubleshooting

API Reference

Explore the REST API endpoints

Troubleshooting

Database connection fails

Check DATABASE_URL: Ensure it’s a valid PostgreSQL connection string
Check SSL mode: Neon requires ?sslmode=require at the end of the URL
Check IP allowlist: Some databases restrict connections by IP

OAuth redirect mismatch

Check redirect URIs: Make sure all URIs are added in Google Cloud Console
Check protocol: Use http:// for localhost and https:// for production
Check trailing slashes: Google is strict about exact URI matches

Build errors

Check Node version: Use Node 20+
Clear cache: Run rm -rf .next node_modules pnpm-lock.yaml && pnpm install
Check TypeScript: Run pnpm build to see type errors

Environment variables not loading

Restart dev server: .env.local changes require a restart
Check file name: It must be exactly .env.local (not .env)
Check deployment platform: Add variables in Vercel/Railway dashboard

Get Started

Core Features

Guides

Deployment

Installation

Installation

Prerequisites

Step 1: Clone and install dependencies

Step 2: Set up the database

Step 3: Configure Google OAuth

Step 4: Configure NextAuth

Step 5: Configure Anthropic API

Step 6: Configure Vercel Cron (optional)

Step 7: Complete environment configuration

Step 8: Run locally

Step 9: Deploy to Vercel (optional)

Step 10: Seed initial data (optional)

Database schema reference

`users`

`workspace_members`

`gmail_accounts`

`categories`

`email_threads`

`emails`

`drafts`

Project structure

Available commands

Next steps

Quickstart

Team Collaboration

Gmail Integration

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Deployment

​Installation

​Prerequisites

​Step 1: Clone and install dependencies

​Step 2: Set up the database

​Step 3: Configure Google OAuth

​Step 4: Configure NextAuth

​Step 5: Configure Anthropic API

​Step 6: Configure Vercel Cron (optional)

​Step 7: Complete environment configuration

​Step 8: Run locally

​Step 9: Deploy to Vercel (optional)

​Step 10: Seed initial data (optional)

​Database schema reference

​users

​workspace_members

​gmail_accounts

​categories

​email_threads

​emails

​drafts

​Project structure

​Available commands

​Next steps

Quickstart

Team Collaboration

Gmail Integration

API Reference

​Troubleshooting

Build docs developers (and LLMs) love

Installation

Prerequisites

Step 1: Clone and install dependencies

Step 2: Set up the database

Step 3: Configure Google OAuth

Step 4: Configure NextAuth

Step 5: Configure Anthropic API

Step 6: Configure Vercel Cron (optional)

Step 7: Complete environment configuration

Step 8: Run locally

Step 9: Deploy to Vercel (optional)

Step 10: Seed initial data (optional)

Database schema reference

`users`

`workspace_members`

`gmail_accounts`

`categories`

`email_threads`

`emails`

`drafts`

Project structure

Available commands

Next steps

Troubleshooting