Skip to main content
Whilst runs as a hybrid architecture:
  • Web App: Next.js on Vercel (app.whilst.io)
  • Bot Backend: AWS Lambda (event-intake + job-worker)
  • Database: Neon PostgreSQL (serverless, shared by web app and bot)
  • Secrets: AWS Secrets Manager

​
Web App (Vercel)

The Next.js web app auto-deploys on push to main via Vercel.

​
Environment Variables

Set these in the Vercel dashboard under Settings → Environment Variables: 
# WorkOS
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=https://app.whilst.io/api/auth/workos/callback

# Session
SESSION_SECRET=your-production-secret

# Database (pooled Neon connection string)
POSTGRES_URL=postgresql://user:pass@ep-xxx-pooler.us-east-1.aws.neon.tech/whilst?sslmode=require

# OpenAI
OPENAI_API_KEY=sk-...

# Application
NEXT_PUBLIC_APP_URL=https://app.whilst.io

​
Deploy

git push origin main
# Vercel auto-deploys

​
Database (Neon)

The database is hosted on Neon (serverless Postgres), not on AWS.
Key differences from traditional Postgres hosting:
  • No VPC, subnets, or security groups — Neon is accessed over the internet with SSL
  • Built-in connection pooler replaces RDS Proxy for Lambda connections
  • Use Neon branches (not snapshots) for dev/staging environments
  • Scale-to-zero billing — pay only for compute hours used

​
Setup

  1. Create a project at console.neon.tech (region: aws-us-east-1)
  2. Enable vector and uuid-ossp extensions
  3. Note two connection strings from the Neon dashboard:
    • Pooled (for app runtime): postgres://...@ep-xxx-pooler.neon.tech/whilst?sslmode=require
    • Direct (for migrations): postgres://...@ep-xxx.neon.tech/whilst?sslmode=require

​
Migrations

Always use the direct (non-pooled) connection string for migrations: 
export POSTGRES_URL="postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/whilst?sslmode=require"
pnpm db:migrate
Always run migrations in staging first (use a Neon branch) and verify before applying to production.

​
Backend Services (AWS)

Lambda functions are deployed via the AWS SDK deploy script.

​
Prerequisites

  • AWS CLI configured with appropriate credentials
  • Node.js 20+ and pnpm 9+

​
Deploy

# Build all packages
pnpm build

# Package Lambda functions
pnpm run package:lambdas

# Deploy infrastructure
pnpm run infra:deploy -- --env staging

​
Staging vs Production

# Deploy to staging
pnpm run infra:deploy -- --env staging

# Deploy to production
pnpm run infra:deploy -- --env production
The deploy script creates/updates Lambdas, SQS queues, and API Gateway. The database is managed separately on Neon.

​
CI/CD

The GitHub Actions workflow (.github/workflows/ci.yml) runs lint, tests, and build on all pushes and PRs against main.

​
Monitoring

  • CloudWatch: Lambda logs and metrics
  • X-Ray: Distributed tracing across services
  • DLQ alerts: SQS dead letter queue failures trigger Slack notifications via SNS
  • Neon Dashboard: Database metrics, query performance, branch management