# 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

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

## Step 2: Create Database

```bash
# Create PostgreSQL database
createdb a2p_autopilot

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

## Step 3: Configure Environment

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

# Edit .env with your credentials
nano .env
```

**Required variables:**
```env
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

```bash
# Generate migration files from schema
npm run db:generate

# Apply migrations to database
npm run db:migrate
```

## Step 5: Start Server

```bash
# 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
```bash
curl http://localhost:3000/health
```

### Create a Submission
```bash
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
```bash
curl http://localhost:3000/api/stats \
  -H "Authorization: Bearer your-secret-api-key-here"
```

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

## Optional: Drizzle Studio (Database GUI)

```bash
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
```bash
# 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
```bash
npm run typecheck
```

### Database Reset (DANGER!)
```bash
# 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