# A2P AutoPilot - Database Schema + API Server

Production-grade PostgreSQL database schema and REST API for managing Twilio A2P brand and campaign registrations.

## 🏗️ Architecture

### Database Schema (Drizzle ORM)
- **submissions** — Main table tracking each A2P registration lifecycle
- **remediation_log** — History of automated fixes applied to failed submissions
- **audit_log** — Complete audit trail of every Twilio API call

### API Server (Express + TypeScript)
- REST API for submission management
- Webhook endpoints for Twilio status updates
- Real-time dashboard statistics
- Bulk import capabilities

## 📦 Installation

```bash
npm install
```

## ⚙️ Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Required environment variables:
- `DATABASE_URL` — PostgreSQL connection string
- `REDIS_URL` — Redis connection string
- `API_KEY` — Authentication key for API endpoints
- `TWILIO_ACCOUNT_SID` — Twilio Account SID
- `TWILIO_AUTH_TOKEN` — Twilio Auth Token

## 🗄️ Database Setup

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

### Run migrations:
```bash
npm run db:migrate
```

### Open Drizzle Studio (database GUI):
```bash
npm run db:studio
```

## 🚀 Running the Server

### Development (with hot reload):
```bash
npm run dev
```

### Production:
```bash
npm run build
npm start
```

## 📡 API Endpoints

### Submissions
- `POST /api/submissions` — Create new A2P registration
- `GET /api/submissions` — List submissions (with filters)
- `GET /api/submissions/:id` — Get submission details
- `POST /api/submissions/:id/retry` — Retry failed submission
- `POST /api/submissions/:id/cancel` — Cancel pending submission
- `GET /api/submissions/:id/audit-log` — Get audit trail
- `POST /api/submissions/bulk` — Bulk import submissions

### Stats
- `GET /api/stats` — Dashboard statistics

### Webhooks (Public)
- `POST /webhooks/twilio/brand` — Twilio brand status webhook
- `POST /webhooks/twilio/campaign` — Twilio campaign status webhook

### Health
- `GET /health` — Health check endpoint

## 🔐 Authentication

All API endpoints (except webhooks and health) require an API key:

```bash
Authorization: Bearer YOUR_API_KEY
```

## 📊 Database Schema Details

### submissions table
Tracks the complete lifecycle of each A2P registration:
- **Status tracking** — 14 different states from `pending` to `completed`
- **SID chain** — All Twilio resource SIDs stored in JSONB
- **Input data** — Full `RegistrationInput` preserved
- **Timestamps** — Detailed tracking of each stage
- **Retry logic** — Attempt count and max attempts
- **Notifications** — Webhook/email configuration

### remediation_log table
Automated fix history:
- What failed
- What fix was applied
- Before/after field changes
- Resubmission timestamp

### audit_log table
Complete audit trail:
- Every Twilio API call
- Full request/response data
- Performance metrics (duration_ms)
- Success/error status

## 🛠️ Tech Stack

- **Database**: PostgreSQL + Drizzle ORM
- **API**: Express.js + TypeScript
- **Queue**: BullMQ + Redis
- **Validation**: Zod
- **Logging**: Pino
- **IDs**: nanoid (collision-resistant, URL-safe)

## 📝 Type Safety

All code uses shared types from `src/types.ts`:
- `RegistrationInput` — User input structure
- `SubmissionRecord` — Full submission with history
- `SubmissionStatus` — 14 lifecycle states
- `SidChain` — All Twilio resource SIDs

## 🔄 Next Steps

The following components need to be implemented:

1. **Landing Page Generator** (`src/landing-page/generator.ts`)
   - Generate compliant landing pages from input data
   - Upload to S3 or static hosting
   
2. **Submission Engine** (`src/engine/submission-engine.ts`)
   - Twilio API client wrapper
   - Multi-step submission orchestration
   - Auto-remediation logic

3. **BullMQ Workers** (`src/workers/`)
   - Polling worker for status updates
   - Submission processing worker
   - Retry/remediation worker

4. **Notification Service** (`src/notifications/`)
   - Webhook delivery
   - Email notifications
   - Status update broadcasting

## 📄 License

MIT