clawdbot-workspace/a2p-autopilot/QUICKSTART.md

Quick Start Guide

Get the A2P AutoPilot API server running in 5 minutes.

Prerequisites

• Node.js 18+ installed
• PostgreSQL running locally or accessible remotely
• Redis running (for BullMQ workers)

Step 1: Install Dependencies

cd /Users/jakeshore/.clawdbot/workspace/a2p-autopilot
npm install

Step 2: Create Database

# Create PostgreSQL database
createdb a2p_autopilot

# Or using psql
psql -c "CREATE DATABASE a2p_autopilot;"

Step 3: Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env with your credentials
nano .env

Required variables:

DATABASE_URL=postgresql://localhost:5432/a2p_autopilot
REDIS_URL=redis://localhost:6379
API_KEY=your-secret-api-key-here
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-twilio-auth-token

Step 4: Run Migrations

# Generate migration files from schema
npm run db:generate

# Apply migrations to database
npm run db:migrate

Step 5: Start Server

# Development mode (with hot reload)
npm run dev

# Or production mode
npm run build
npm start

Server will start on http://localhost:3000

Step 6: Test the API

Health Check

curl http://localhost:3000/health

Create a Submission

curl -X POST http://localhost:3000/api/submissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-api-key-here" \
  -d @test-submission.json

Get Stats

curl http://localhost:3000/api/stats \
  -H "Authorization: Bearer your-secret-api-key-here"

List Submissions

curl "http://localhost:3000/api/submissions?status=pending&limit=10" \
  -H "Authorization: Bearer your-secret-api-key-here"

Optional: Drizzle Studio (Database GUI)

npm run db:studio

Opens a web-based database GUI at https://local.drizzle.studio

Troubleshooting

Database Connection Error

• Verify PostgreSQL is running: pg_isready
• Check DATABASE_URL in .env is correct
• Ensure database exists: psql -l | grep a2p_autopilot

Redis Connection Error

• Verify Redis is running: redis-cli ping
• Should return "PONG"
• Check REDIS_URL in .env

Port Already in Use

• Change PORT in .env
• Or kill process: lsof -ti:3000 | xargs kill

Migration Errors

• Delete drizzle/ folder and regenerate: rm -rf drizzle && npm run db:generate
• Drop and recreate database if needed

Next Steps

1. Review API Documentation — See README.md for all endpoints
2. Integrate Landing Pages — Connect the pages/ module
3. Wire Up Submission Engine — Connect the engine/ module
4. Enable Polling — Start BullMQ workers for status updates
5. Test Webhooks — Use ngrok to test Twilio webhooks locally

Development Tips

Watch Database Changes

# Terminal 1: Run server
npm run dev

# Terminal 2: Watch database
npm run db:studio

Check Logs

Logs are pretty-printed in development with colors and timestamps.

Type Checking

npm run typecheck

Database Reset (DANGER!)

# Drop all tables and re-migrate
psql a2p_autopilot -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
npm run db:migrate

Production Deployment

See README.md for production deployment checklist including:

• Environment variable security
• Database connection pooling
• Redis clustering
• Process management (PM2/systemd)
• Reverse proxy (nginx)
• SSL/TLS configuration
• Log aggregation
• Monitoring and alerting