Skip to main content
Get Drift running locally for development in minutes.

​
Prerequisites

Ensure you have the following installed:

​
Installation

1

Clone the repository

git clone https://github.com/aadit2805/drift.git
cd drift
2

Install Node.js dependencies

The monorepo uses npm workspaces managed by Turborepo.
npm install
This installs dependencies for:
  • Root workspace (Turborepo)
  • apps/web (Next.js frontend)
  • apps/api (Express backend)
3

Set up Python environment (optional)

For faster Monte Carlo simulations, set up the Python environment:
cd simulation
python3 -m venv venv

# On macOS/Linux
source venv/bin/activate

# On Windows
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
cd ..
The Python simulation engine is optional. The app can run simulations in TypeScript if Python is not configured.
4

Configure environment variables

Create a .env file at the repository root:
touch .env
Add your API keys (see Environment Variables):
.env
NESSIE_API_KEY=your_nessie_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here  # Optional
At minimum, you need NESSIE_API_KEY and GEMINI_API_KEY to run the app.

​
Running the Development Server

​
Project Structure

drift/
├── apps/
│   ├── web/              # Next.js frontend (port 3000)
│   │   ├── app/          # Next.js 14 App Router pages
│   │   ├── components/   # React components
│   │   ├── lib/          # API client, utilities
│   │   └── types/        # TypeScript types
│   └── api/              # Express backend (port 3001)
│       ├── src/
│       │   ├── routes/   # API endpoints
│       │   ├── services/ # Business logic (Nessie, Gemini, etc.)
│       │   ├── types/    # TypeScript types
│       │   └── index.ts  # Express app entry point
│       └── package.json
├── simulation/           # Python Monte Carlo engine
│   ├── simulate.py       # Main simulation script
│   ├── requirements.txt  # Python dependencies
│   └── venv/            # Python virtual environment
├── scripts/              # Utilities
│   └── seed-nessie.ts   # Seed demo data
├── docs/                 # Documentation
├── package.json          # Root workspace
├── turbo.json           # Turborepo configuration
└── .env                 # Environment variables (create this)

​
Development Workflow

​
Making Changes

Both the API and web app support hot reload:
  • API (Express + tsx): Automatically restarts on file changes in apps/api/src/
  • Web (Next.js): Fast Refresh updates the browser on changes in apps/web/

​
Running Linters

npm run lint
This runs ESLint across all workspaces.

​
Building for Production

npm run build
This builds:
  • apps/api - TypeScript compiled to dist/
  • apps/web - Next.js optimized production build in .next/

​
Seeding Demo Data

Populate the Nessie API with demo customer data: 
npm run seed
This creates:
  • Demo customer (Alex Morgan)
  • Bank accounts (checking, savings, credit card)
  • 12 months of realistic transaction history
  • Merchants with categories

​
Testing the API

curl http://localhost:3001/health

​
Common Issues

If ports 3000 or 3001 are already in use:
# Kill process on port 3001
lsof -ti:3001 | xargs kill -9

# Or change the port in .env
PORT=3002
If you see “NESSIE_API_KEY not set” warnings:
  1. Ensure your .env file is at the repository root (not in apps/api/)
  2. Verify the environment variables are loaded: 
    echo $NESSIE_API_KEY  # Should print your key
  3. Restart the dev server after adding keys
If simulations fail or are slow:
  1. Check if Python virtual environment is activated
  2. Verify NumPy is installed: pip list | grep numpy
  3. The app falls back to TypeScript simulation if Python fails
The Gemini 2.0 Flash model has rate limits. If you hit them:
  1. Wait a minute and try again
  2. The app falls back to mock parsing automatically
  3. Consider upgrading to a paid Gemini API plan
If you see TypeScript module errors:
# Clear node_modules and reinstall
rm -rf node_modules apps/*/node_modules
npm install

​
Next Steps

Environment Variables

Configure all required API keys

Production Deployment

Deploy Drift to production

API Reference

Explore available API endpoints

Architecture

Understand how Drift works

Build docs developers (and LLMs) love

Get started for freeTalk to us