┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                            │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐ │
│  │ Debtor Portal  │  │Business Dashboard│  │  Admin Panel     │ │
│  │   React SPA    │  │   React SPA     │  │   React SPA      │ │
│  │   Port: 3000   │  │   Port: 3001    │  │   Port: 3002     │ │
│  └────────────────┘  └────────────────┘  └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                 ↓ HTTPS
┌─────────────────────────────────────────────────────────────────┐
│                      LOAD BALANCER / CDN                        │
│                      (CloudFlare / AWS ALB)                     │
└─────────────────────────────────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────┐
│                         API GATEWAY                             │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │  Express.js API Server (Node.js + TypeScript)             │ │
│  │  - JWT Authentication Middleware                          │ │
│  │  - Rate Limiting (1000 req/min per IP)                    │ │
│  │  - Request Validation (Joi/Zod)                           │ │
│  │  - Error Handling                                         │ │
│  │  - CORS Configuration                                     │ │
│  │  Port: 4000                                               │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────┐
│                      APPLICATION SERVICES                       │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │   Chatbot    │  │   Payment    │  │    Analytics       │  │
│  │   Service    │  │   Service    │  │    Service         │  │
│  │              │  │              │  │                    │  │
│  │ - AI Routing │  │ - Stripe     │  │ - Data Aggregation│  │
│  │ - Claude API │  │ - Plans      │  │ - Report Builder  │  │
│  │ - Sentiment  │  │ - Retry      │  │ - Predictions     │  │
│  │ - Compliance │  │   Logic      │  │ - Dashboards      │  │
│  └──────────────┘  └──────────────┘  └────────────────────┘  │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │Notification  │  │  Compliance  │  │    User/Account    │  │
│  │  Service     │  │   Service    │  │    Service         │  │
│  │              │  │              │  │                    │  │
│  │ - SMS/Twilio │  │ - FDCPA      │  │ - Auth             │  │
│  │ - Email/SG   │  │ - TCPA       │  │ - RBAC             │  │
│  │ - WhatsApp   │  │ - Audit Log  │  │ - Profile Mgmt     │  │
│  │ - Push       │  │ - Encryption │  │ - Team Mgmt        │  │
│  └──────────────┘  └──────────────┘  └────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────┐
│                    BACKGROUND JOB PROCESSOR                     │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │  Bull Queue (Redis-backed)                                │ │
│  │  - Scheduled message sending                              │ │
│  │  - Payment retry processing                               │ │
│  │  - Report generation                                      │ │
│  │  - Data cleanup jobs                                      │ │
│  │  - Analytics aggregation                                  │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────┐
│                   THIRD-PARTY INTEGRATIONS                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │Anthropic │  │  Stripe  │  │  Twilio  │  │   SendGrid   │  │
│  │ Claude   │  │ Payments │  │  SMS/WA  │  │    Email     │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────────────────┐
│                         DATA LAYER                              │
│  ┌────────────────┐  ┌─────────────┐  ┌──────────────────┐   │
│  │  PostgreSQL    │  │    Redis    │  │   AWS S3         │   │
│  │  (Primary DB)  │  │   (Cache)   │  │ (File Storage)   │   │
│  │                │  │             │  │                  │   │
│  │ - Users        │  │ - Sessions  │  │ - Documents      │   │
│  │ - Accounts     │  │ - Job Queue │  │ - Attachments    │   │
│  │ - Messages     │  │ - Rate Limit│  │ - Exports        │   │
│  │ - Payments     │  │ - Real-time │  │ - Backups        │   │
│  │ - Audit Logs   │  │   Data      │  │                  │   │
│  │                │  │             │  │                  │   │
│  │  Port: 5432    │  │  Port: 6379 │  │  HTTPS API       │   │
│  └────────────────┘  └─────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

1. User submits email + password
2. API validates credentials against database (bcrypt hash comparison)
3. If valid, generate JWT token (payload: userId, email, role, exp)
4. Return token + user object to client
5. Client stores token in localStorage (or httpOnly cookie)
6. Client includes token in Authorization header for all requests
7. API middleware validates token on each request
8. If token expired or invalid, return 401 Unauthorized

{
  "userId": "uuid-here",
  "email": "user@example.com",
  "role": "agent",
  "businessId": "uuid-here",
  "iat": 1700000000,
  "exp": 1700604800
}

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│  businesses │────────<│    users     │>────────│   sessions  │
└─────────────┘         └──────────────┘         └─────────────┘
       │                        │
       │                        │
       ├────────────────────────┤
       │                        │
       ∨                        ∨
┌─────────────┐         ┌──────────────┐
│   accounts  │────────<│conversations │
└─────────────┘         └──────────────┘
       │                        │
       │                        │
       ∨                        ∨
┌─────────────┐         ┌──────────────┐
│   payments  │         │   messages   │
└─────────────┘         └──────────────┘
       │
       │
       ∨
┌─────────────┐
│payment_plans│
└─────────────┘

CREATE TABLE businesses (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    phone VARCHAR(20),
    address TEXT,
    website VARCHAR(255),
    
    -- Stripe billing
    stripe_customer_id VARCHAR(255) UNIQUE,
    stripe_subscription_id VARCHAR(255),
    subscription_tier VARCHAR(20) DEFAULT 'free', -- free, basic, premium
    subscription_status VARCHAR(20) DEFAULT 'active', -- active, canceled, past_due
    
    -- Usage tracking
    message_quota INT DEFAULT 0, -- Monthly message allowance
    messages_used_this_month INT DEFAULT 0,
    billing_period_start DATE,
    billing_period_end DATE,
    
    -- Settings
    settings JSONB DEFAULT '{}', -- {autoResponseEnabled, timezone, etc}
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP -- Soft delete
);

CREATE INDEX idx_businesses_stripe_customer ON businesses(stripe_customer_id);
CREATE INDEX idx_businesses_email ON businesses(email);

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
    
    -- Authentication
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL, -- bcrypt hash
    phone VARCHAR(20),
    
    -- Profile
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    avatar_url VARCHAR(500),
    
    -- Role & Permissions
    role VARCHAR(20) NOT NULL, -- super_admin, business_admin, manager, agent, debtor
    permissions JSONB DEFAULT '[]', -- Array of permission strings
    
    -- Status
    status VARCHAR(20) DEFAULT 'active', -- active, inactive, suspended
    email_verified BOOLEAN DEFAULT false,
    email_verification_token VARCHAR(255),
    
    -- MFA
    mfa_enabled BOOLEAN DEFAULT false,
    mfa_secret VARCHAR(255),
    
    -- Password reset
    password_reset_token VARCHAR(255),
    password_reset_expires TIMESTAMP,
    
    -- Timestamps
    last_login_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_business ON users(business_id);
CREATE INDEX idx_users_role ON users(role);
CREATE UNIQUE INDEX idx_users_email_verification ON users(email_verification_token) WHERE email_verification_token IS NOT NULL;
CREATE UNIQUE INDEX idx_users_password_reset ON users(password_reset_token) WHERE password_reset_token IS NOT NULL;

CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token VARCHAR(500) NOT NULL UNIQUE, -- JWT token (or hash of it)
    
    -- Session metadata
    ip_address VARCHAR(45), -- IPv4 or IPv6
    user_agent TEXT,
    
    -- Expiry
    expires_at TIMESTAMP NOT NULL,
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    last_activity_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_sessions_user ON sessions(user_id);
CREATE INDEX idx_sessions_token ON sessions(token);
CREATE INDEX idx_sessions_expires ON sessions(expires_at);

CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID NOT NULL REFERENCES businesses(id) ON DELETE CASCADE,
    debtor_id UUID REFERENCES users(id) ON DELETE SET NULL, -- Linked user account (optional)
    
    -- Debtor information
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    email VARCHAR(255),
    phone VARCHAR(20),
    phone_secondary VARCHAR(20),
    address TEXT,
    city VARCHAR(100),
    state VARCHAR(50),
    zip VARCHAR(20),
    country VARCHAR(50) DEFAULT 'US',
    
    -- Account details
    account_number VARCHAR(100) UNIQUE,
    original_creditor VARCHAR(255),
    current_balance DECIMAL(10, 2) NOT NULL,
    original_balance DECIMAL(10, 2),
    due_date DATE,
    
    -- Status
    status VARCHAR(20) DEFAULT 'active', -- active, in_payment_plan, paid_in_full, disputed, legal, closed
    
    -- Metadata
    tags TEXT[], -- Array of tags: ['high_priority', 'medical', etc]
    notes TEXT, -- Internal notes
    custom_fields JSONB DEFAULT '{}', -- Extensible custom data
    
    -- Communication preferences
    preferred_language VARCHAR(10) DEFAULT 'en', -- en, es
    preferred_contact_method VARCHAR(20), -- sms, email, whatsapp
    timezone VARCHAR(50) DEFAULT 'America/New_York',
    do_not_contact BOOLEAN DEFAULT false,
    do_not_sms BOOLEAN DEFAULT false,
    do_not_email BOOLEAN DEFAULT false,
    do_not_call BOOLEAN DEFAULT false,
    
    -- Consent tracking
    sms_consent BOOLEAN DEFAULT false,
    sms_consent_date TIMESTAMP,
    email_consent BOOLEAN DEFAULT false,
    email_consent_date TIMESTAMP,
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP
);

CREATE INDEX idx_accounts_business ON accounts(business_id);
CREATE INDEX idx_accounts_debtor ON accounts(debtor_id);
CREATE INDEX idx_accounts_email ON accounts(email);
CREATE INDEX idx_accounts_phone ON accounts(phone);
CREATE INDEX idx_accounts_account_number ON accounts(account_number);
CREATE INDEX idx_accounts_status ON accounts(status);
CREATE INDEX idx_accounts_tags ON accounts USING GIN(tags);

CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
    business_id UUID NOT NULL REFERENCES businesses(id) ON DELETE CASCADE,
    
    -- Assignment
    assigned_agent_id UUID REFERENCES users(id) ON DELETE SET NULL,
    assigned_at TIMESTAMP,
    
    -- Channel
    channel VARCHAR(20) NOT NULL, -- sms, whatsapp, email, web_chat
    
    -- Status
    status VARCHAR(20) DEFAULT 'active', -- active, resolved, escalated, closed
    resolution_type VARCHAR(50), -- paid, payment_plan, dispute, other
    
    -- Metadata
    subject VARCHAR(255), -- For email conversations
    last_message_at TIMESTAMP,
    last_message_from VARCHAR(20), -- agent, debtor, ai
    
    -- AI metrics
    ai_handled BOOLEAN DEFAULT false, -- Was conversation fully handled by AI?
    ai_confidence_avg DECIMAL(3, 2), -- Average AI confidence (0.00 to 1.00)
    sentiment VARCHAR(20), -- positive, neutral, negative, hostile
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    closed_at TIMESTAMP
);

CREATE INDEX idx_conversations_account ON conversations(account_id);
CREATE INDEX idx_conversations_business ON conversations(business_id);
CREATE INDEX idx_conversations_agent ON conversations(assigned_agent_id);
CREATE INDEX idx_conversations_status ON conversations(status);
CREATE INDEX idx_conversations_channel ON conversations(channel);
CREATE INDEX idx_conversations_created ON conversations(created_at);

CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
    
    -- Sender/Recipient
    sender_type VARCHAR(20) NOT NULL, -- agent, debtor, ai, system
    sender_id UUID REFERENCES users(id) ON DELETE SET NULL,
    
    -- Content
    content TEXT NOT NULL,
    content_type VARCHAR(20) DEFAULT 'text', -- text, image, document
    
    -- Attachments
    attachment_url VARCHAR(500),
    attachment_filename VARCHAR(255),
    attachment_size INT, -- bytes
    
    -- Delivery
    direction VARCHAR(10) NOT NULL, -- inbound, outbound
    delivery_status VARCHAR(20) DEFAULT 'pending', -- pending, sent, delivered, failed, read
    delivered_at TIMESTAMP,
    read_at TIMESTAMP,
    failed_reason TEXT,
    
    -- External IDs (for third-party services)
    twilio_sid VARCHAR(100), -- Twilio message SID
    sendgrid_id VARCHAR(100), -- SendGrid message ID
    
    -- AI metadata (if AI-generated)
    ai_generated BOOLEAN DEFAULT false,
    ai_confidence DECIMAL(3, 2), -- 0.00 to 1.00
    ai_model VARCHAR(50), -- e.g., "claude-sonnet-4"
    
    -- Compliance
    compliance_checked BOOLEAN DEFAULT false,
    compliance_passed BOOLEAN DEFAULT true,
    compliance_issues TEXT[],
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_messages_conversation ON messages(conversation_id);
CREATE INDEX idx_messages_sender ON messages(sender_id);
CREATE INDEX idx_messages_created ON messages(created_at);
CREATE INDEX idx_messages_delivery_status ON messages(delivery_status);

CREATE TABLE payments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
    payment_plan_id UUID REFERENCES payment_plans(id) ON DELETE SET NULL,
    
    -- Payment details
    amount DECIMAL(10, 2) NOT NULL,
    currency VARCHAR(3) DEFAULT 'USD',
    payment_method VARCHAR(20) NOT NULL, -- card, ach, check, cash
    
    -- Stripe
    stripe_payment_intent_id VARCHAR(255),
    stripe_charge_id VARCHAR(255),
    
    -- Status
    status VARCHAR(20) DEFAULT 'pending', -- pending, succeeded, failed, refunded
    failure_reason TEXT,
    
    -- Receipt
    receipt_url VARCHAR(500),
    receipt_number VARCHAR(100),
    
    -- Metadata
    description TEXT,
    notes TEXT,
    processed_by_id UUID REFERENCES users(id), -- Agent who processed (if manual)
    
    -- Timestamps
    processed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_payments_account ON payments(account_id);
CREATE INDEX idx_payments_plan ON payments(payment_plan_id);
CREATE INDEX idx_payments_status ON payments(status);
CREATE INDEX idx_payments_stripe_intent ON payments(stripe_payment_intent_id);
CREATE INDEX idx_payments_created ON payments(created_at);

CREATE TABLE payment_plans (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
    
    -- Plan details
    total_amount DECIMAL(10, 2) NOT NULL,
    down_payment DECIMAL(10, 2) DEFAULT 0,
    installment_amount DECIMAL(10, 2) NOT NULL,
    number_of_installments INT NOT NULL,
    frequency VARCHAR(20) NOT NULL, -- weekly, biweekly, monthly
    
    -- Schedule
    start_date DATE NOT NULL,
    next_payment_date DATE,
    
    -- Status
    status VARCHAR(20) DEFAULT 'pending', -- pending, active, completed, defaulted, canceled
    payments_made INT DEFAULT 0,
    amount_paid DECIMAL(10, 2) DEFAULT 0,
    
    -- Auto-pay
    auto_pay_enabled BOOLEAN DEFAULT false,
    stripe_payment_method_id VARCHAR(255),
    
    -- Agreement
    agreement_signed BOOLEAN DEFAULT false,
    agreement_signed_at TIMESTAMP,
    agreement_ip_address VARCHAR(45),
    
    -- Metadata
    created_by_id UUID REFERENCES users(id), -- Agent who created plan
    notes TEXT,
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP,
    canceled_at TIMESTAMP
);

CREATE INDEX idx_payment_plans_account ON payment_plans(account_id);
CREATE INDEX idx_payment_plans_status ON payment_plans(status);
CREATE INDEX idx_payment_plans_next_payment ON payment_plans(next_payment_date);

CREATE TABLE campaigns (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID NOT NULL REFERENCES businesses(id) ON DELETE CASCADE,
    
    -- Campaign details
    name VARCHAR(255) NOT NULL,
    description TEXT,
    
    -- Targeting
    target_filter JSONB, -- Account filter criteria
    target_account_ids UUID[], -- Or explicit list of account IDs
    
    -- Message
    channel VARCHAR(20) NOT NULL, -- sms, email, whatsapp
    message_template TEXT NOT NULL,
    subject_template VARCHAR(255), -- For email
    
    -- Schedule
    schedule_type VARCHAR(20) NOT NULL, -- immediate, scheduled, recurring
    scheduled_at TIMESTAMP,
    timezone VARCHAR(50),
    recurrence_rule VARCHAR(100), -- e.g., "daily", "weekly"
    
    -- Status
    status VARCHAR(20) DEFAULT 'draft', -- draft, scheduled, running, completed, paused, canceled
    
    -- Metrics
    target_count INT DEFAULT 0,
    sent_count INT DEFAULT 0,
    delivered_count INT DEFAULT 0,
    response_count INT DEFAULT 0,
    payment_count INT DEFAULT 0,
    payment_amount DECIMAL(10, 2) DEFAULT 0,
    
    -- Metadata
    created_by_id UUID REFERENCES users(id),
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    started_at TIMESTAMP,
    completed_at TIMESTAMP
);

CREATE INDEX idx_campaigns_business ON campaigns(business_id);
CREATE INDEX idx_campaigns_status ON campaigns(status);
CREATE INDEX idx_campaigns_scheduled ON campaigns(scheduled_at);

CREATE TABLE audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
    
    -- Who
    user_id UUID REFERENCES users(id) ON DELETE SET NULL,
    user_email VARCHAR(255),
    user_role VARCHAR(20),
    
    -- What
    action VARCHAR(100) NOT NULL, -- login, create_account, send_message, etc
    resource_type VARCHAR(50), -- account, message, payment, etc
    resource_id UUID,
    
    -- Details
    description TEXT,
    changes JSONB, -- Before/after values
    metadata JSONB, -- Additional context
    
    -- Context
    ip_address VARCHAR(45),
    user_agent TEXT,
    
    -- Status
    success BOOLEAN DEFAULT true,
    error_message TEXT,
    
    -- Timestamp
    created_at TIMESTAMP DEFAULT NOW()
);

-- Partitioning recommended for large datasets
CREATE INDEX idx_audit_logs_business ON audit_logs(business_id);
CREATE INDEX idx_audit_logs_user ON audit_logs(user_id);
CREATE INDEX idx_audit_logs_action ON audit_logs(action);
CREATE INDEX idx_audit_logs_resource ON audit_logs(resource_type, resource_id);
CREATE INDEX idx_audit_logs_created ON audit_logs(created_at);

CREATE TABLE documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID NOT NULL REFERENCES businesses(id) ON DELETE CASCADE,
    account_id UUID REFERENCES accounts(id) ON DELETE CASCADE,
    conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
    
    -- File details
    filename VARCHAR(255) NOT NULL,
    file_type VARCHAR(50), -- pdf, jpg, png, docx, etc
    file_size INT NOT NULL, -- bytes
    mime_type VARCHAR(100),
    
    -- Storage
    storage_path VARCHAR(500) NOT NULL, -- S3 key or file path
    storage_url VARCHAR(500), -- Signed URL for access
    
    -- Classification
    document_type VARCHAR(50), -- invoice, agreement, letter, photo, other
    
    -- Metadata
    uploaded_by_id UUID REFERENCES users(id),
    description TEXT,
    tags TEXT[],
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    deleted_at TIMESTAMP
);

CREATE INDEX idx_documents_business ON documents(business_id);
CREATE INDEX idx_documents_account ON documents(account_id);
CREATE INDEX idx_documents_conversation ON documents(conversation_id);
CREATE INDEX idx_documents_type ON documents(document_type);

CREATE TABLE templates (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    business_id UUID REFERENCES businesses(id) ON DELETE CASCADE,
    
    -- Template details
    name VARCHAR(255) NOT NULL,
    description TEXT,
    template_type VARCHAR(50) NOT NULL, -- sms, email, agreement, letter
    
    -- Content
    subject VARCHAR(255), -- For email templates
    body TEXT NOT NULL,
    variables TEXT[], -- Available variables: firstName, balance, etc
    
    -- Settings
    is_default BOOLEAN DEFAULT false,
    is_active BOOLEAN DEFAULT true,
    
    -- Metadata
    created_by_id UUID REFERENCES users(id),
    
    -- Timestamps
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_templates_business ON templates(business_id);
CREATE INDEX idx_templates_type ON templates(template_type);

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email"
  }
}

{
  "email": "john@example.com",
  "password": "SecurePass123!",
  "firstName": "John",
  "lastName": "Doe",
  "role": "debtor",
  "businessId": "uuid-here" // Optional, for business users
}

{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "debtor"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

{
  "email": "john@example.com",
  "password": "SecurePass123!"
}

{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "debtor",
      "businessId": "uuid"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

{
  "email": "john@example.com"
}

{
  "success": true,
  "data": {
    "message": "Password reset email sent"
  }
}

{
  "token": "reset-token-from-email",
  "newPassword": "NewSecurePass123!"
}

{
  "success": true,
  "data": {
    "message": "Password reset successful"
  }
}

Authorization: Bearer {token}

GET /api/v1/accounts?page=1&limit=20&status=active&sortBy=balance&sortOrder=desc

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "accountNumber": "ACC-001",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "currentBalance": 1250.00,
      "dueDate": "2025-12-31",
      "status": "active",
      "tags": ["medical", "high_priority"],
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountNumber": "ACC-001",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "currentBalance": 1250.00,
    "originalBalance": 1500.00,
    "dueDate": "2025-12-31",
    "status": "active",
    "originalCreditor": "ABC Hospital",
    "tags": ["medical", "high_priority"],
    "notes": "Patient recently lost job",
    "preferredLanguage": "en",
    "preferredContactMethod": "sms",
    "smsConsent": true,
    "emailConsent": true,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-11-20T14:30:00Z"
  }
}

Authorization: Bearer {token}

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip": "10001",
  "accountNumber": "ACC-001", // Optional, auto-generated if not provided
  "originalCreditor": "ABC Hospital",
  "currentBalance": 1250.00,
  "originalBalance": 1500.00,
  "dueDate": "2025-12-31",
  "tags": ["medical"],
  "notes": "Patient recently lost job",
  "smsConsent": true,
  "emailConsent": true
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountNumber": "ACC-001",
    // ... full account object
  }
}

Authorization: Bearer {token}

{
  "phone": "+15559876543",
  "email": "newemail@example.com",
  "address": "456 Oak Ave",
  "status": "in_payment_plan",
  "tags": ["medical", "hardship"],
  "notes": "Updated contact info"
}

{
  "success": true,
  "data": {
    // ... updated account object
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "message": "Account deleted successfully"
  }
}

Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [CSV file]

firstName,lastName,email,phone,accountNumber,currentBalance,dueDate
Jane,Smith,jane@example.com,+15551234567,ACC-001,1250.00,2025-12-31

{
  "success": true,
  "data": {
    "imported": 45,
    "failed": 2,
    "errors": [
      {
        "row": 10,
        "error": "Invalid email format"
      },
      {
        "row": 23,
        "error": "Duplicate account number"
      }
    ]
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "accountId": "uuid",
      "account": {
        "firstName": "Jane",
        "lastName": "Smith",
        "accountNumber": "ACC-001"
      },
      "channel": "sms",
      "status": "active",
      "assignedAgentId": "uuid",
      "assignedAgent": {
        "firstName": "Mike",
        "lastName": "Agent"
      },
      "lastMessageAt": "2025-11-23T10:30:00Z",
      "lastMessageFrom": "debtor",
      "messageCount": 12,
      "sentiment": "neutral",
      "createdAt": "2025-11-20T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 75
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "account": {
      "firstName": "Jane",
      "lastName": "Smith",
      "currentBalance": 1250.00
    },
    "channel": "sms",
    "status": "active",
    "assignedAgentId": "uuid",
    "messages": [
      {
        "id": "uuid",
        "senderType": "ai",
        "content": "Hi Jane, this is a reminder about your outstanding balance of $1,250. Would you like to discuss payment options?",
        "direction": "outbound",
        "deliveryStatus": "delivered",
        "createdAt": "2025-11-20T14:00:00Z"
      },
      {
        "id": "uuid",
        "senderType": "debtor",
        "content": "I'm having trouble making the full payment. Can I set up a plan?",
        "direction": "inbound",
        "deliveryStatus": "delivered",
        "createdAt": "2025-11-20T14:05:00Z"
      }
    ],
    "createdAt": "2025-11-20T14:00:00Z"
  }
}

Authorization: Bearer {token}

{
  "accountId": "uuid",
  "channel": "sms",
  "initialMessage": "Hi Jane, this is a reminder about your outstanding balance."
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "channel": "sms",
    "status": "active",
    "messages": [
      {
        "id": "uuid",
        "content": "Hi Jane, this is a reminder about your outstanding balance.",
        "deliveryStatus": "sent"
      }
    ]
  }
}

Authorization: Bearer {token}

{
  "content": "We can set up a payment plan. How much can you afford monthly?",
  "senderType": "agent" // or "ai"
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "conversationId": "uuid",
    "senderType": "agent",
    "content": "We can set up a payment plan. How much can you afford monthly?",
    "deliveryStatus": "sent",
    "createdAt": "2025-11-23T10:35:00Z"
  }
}

Authorization: Bearer {token}

{
  "assignedAgentId": "uuid",
  "status": "resolved",
  "resolutionType": "payment_plan"
}

{
  "success": true,
  "data": {
    // ... updated conversation
  }
}

Authorization: Bearer {token}

{
  "accountId": "uuid",
  "amount": 100.00,
  "paymentMethod": "card",
  "stripePaymentMethodId": "pm_xxxx", // From Stripe.js frontend
  "description": "Partial payment on account"
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "amount": 100.00,
    "status": "succeeded",
    "receiptUrl": "https://stripe.com/receipts/...",
    "createdAt": "2025-11-23T10:40:00Z"
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "amount": 100.00,
      "status": "succeeded",
      "paymentMethod": "card",
      "receiptUrl": "https://...",
      "createdAt": "2025-11-23T10:40:00Z"
    }
  ]
}

Authorization: Bearer {token}

{
  "accountId": "uuid",
  "totalAmount": 1250.00,
  "downPayment": 250.00,
  "numberOfInstallments": 10,
  "frequency": "monthly",
  "startDate": "2025-12-01",
  "autoPayEnabled": true,
  "stripePaymentMethodId": "pm_xxxx" // Required if autoPayEnabled
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "accountId": "uuid",
    "totalAmount": 1250.00,
    "downPayment": 250.00,
    "installmentAmount": 100.00,
    "numberOfInstallments": 10,
    "frequency": "monthly",
    "startDate": "2025-12-01",
    "nextPaymentDate": "2025-12-01",
    "status": "pending", // Changes to "active" after down payment
    "schedule": [
      {
        "installmentNumber": 1,
        "amount": 100.00,
        "dueDate": "2025-12-01"
      },
      // ... 9 more
    ]
  }
}

{
  "nextPaymentDate": "2025-12-15", // Reschedule
  "status": "paused" // Pause plan
}

Authorization: Bearer {token}

{
  "name": "30-Day Past Due Reminder",
  "description": "Automated reminder for accounts 30+ days past due",
  "channel": "sms",
  "messageTemplate": "Hi {firstName}, your account {accountNumber} is past due. Current balance: ${balance}. Reply to discuss payment options.",
  "targetFilter": {
    "status": "active",
    "daysPastDue": { "gte": 30 }
  },
  "scheduleType": "scheduled",
  "scheduledAt": "2025-11-25T09:00:00Z"
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "30-Day Past Due Reminder",
    "status": "scheduled",
    "targetCount": 120,
    "scheduledAt": "2025-11-25T09:00:00Z"
  }
}

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "30-Day Past Due Reminder",
    "status": "completed",
    "targetCount": 120,
    "sentCount": 118,
    "deliveredCount": 115,
    "responseCount": 45,
    "paymentCount": 12,
    "paymentAmount": 5420.00,
    "roi": 4.58 // Payment amount / campaign cost
  }
}

Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "totalAccounts": 850,
    "totalOutstanding": 1250000.00,
    "collectionsThisMonth": 125000.00,
    "collectionRate": 10.0, // percentage
    "activeConversations": 45,
    "messagesSentToday": 230,
    "messagesReceivedToday": 105,
    "paymentSuccessRate": 92.5,
    "aiHandledRate": 78.0
  }
}