clawdbot-workspace/a2p-autopilot/README.md

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

npm install

⚙️ Configuration

Copy .env.example to .env and configure:

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:

npm run db:generate

Run migrations:

npm run db:migrate

Open Drizzle Studio (database GUI):

npm run db:studio

🚀 Running the Server

Development (with hot reload):

npm run dev

Production:

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:

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