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:

​
Deploy

​
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:
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

​
Staging vs 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