166 lines
4.1 KiB
Markdown
166 lines
4.1 KiB
Markdown
# 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
|