Technical Documentation

Complete guide to the Blue Wireless integration platform. This documentation covers architecture, setup, API reference, and best practices for extending the system.

System Architecture

The integration platform is built on a serverless, event-driven architecture using Azure Functions. Each component is independently deployable and scales automatically based on load.

Core Components

Event Listener: Azure Function triggered by Table Storage events (HTTP webhook)
Ticket Creator: Transforms storage events into Zendesk ticket payloads
AI Classifier: ML model hosted on Azure ML for ticket categorization
Provider Gateway: Unified API interface for external network provider APIs
Webhook Handler: Processes bidirectional updates from Zendesk

Local Development Setup

Clone the repository and install dependencies. Requires Node.js 20+ and Azure Functions Core Tools v4.

# Clone repository
git clone https://github.com/bluewireless/integration-platform.git
cd integration-platform

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Configure Azure credentials
az login
az account set --subscription "Blue Wireless Production"

# Start local development server
npm run dev

Environment Variables

AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
ZENDESK_SUBDOMAIN=bluewireless
ZENDESK_API_TOKEN=your_api_token_here
ZENDESK_EMAIL=api@bluewireless.com
AI_MODEL_ENDPOINT=https://ml.azure.com/models/ticket-classifier
PROVIDER_API_KEY_A=provider_a_key
PROVIDER_API_KEY_B=provider_b_key

Azure Table Storage Integration

The platform listens for row insertion events in the NetworkEvents table. Each row represents a network incident that should generate a Zendesk ticket.

Expected Schema

interface NetworkEvent {
  partitionKey: string;    // Account ID
  rowKey: string;          // Event timestamp
  eventType: 'outage' | 'degradation' | 'maintenance';
  severity: 1 | 2 | 3 | 4;
  affectedServices: string[];
  customerImpact: number;  // Estimated affected users
  description: string;
  metadata: Record;
}

Triggering a Ticket

When a row is inserted, the Azure Function receives a webhook payload within 200ms. The function validates the schema, enriches with provider data, and creates a Zendesk ticket with custom fields mapped from the event metadata.

Zendesk API Integration

Bidirectional sync with Zendesk Support. Tickets are created via REST API, and updates are received through webhooks configured in Zendesk admin.

Ticket Creation Flow

async function createZendeskTicket(event: NetworkEvent) {
  const ticket = {
    subject: `Network ${event.eventType} - Account ${event.partitionKey}`,
    description: event.description,
    priority: mapSeverityToPriority(event.severity),
    custom_fields: [
      { id: 360001234567, value: event.eventType },
      { id: 360001234568, value: event.affectedServices.join(',') },
      { id: 360001234569, value: event.customerImpact.toString() }
    ],
    tags: ['auto-generated', 'network-event', event.eventType]
  };
  
  const response = await zendeskClient.tickets.create({ ticket });
  return response.ticket.id;
}

AI Agent Configuration

The AI agent uses a fine-tuned BERT model trained on 2 years of historical ticket data. It analyzes ticket content, network telemetry, and customer history to determine if auto-resolution is possible.

Resolution Criteria

Confidence score above 85%
Issue type matches trained categories (password reset, service restart, config update)
No active escalations for the same account in past 7 days
Customer tier allows automated actions (Enterprise+ only)

Training the Model

# Export training data from Zendesk
npm run export-tickets --start-date=2022-01-01

# Preprocess and label dataset
npm run preprocess-data

# Train model on Azure ML
az ml job create --file train-config.yml

# Deploy to production endpoint
az ml online-endpoint update --name ticket-classifier

API Reference

POST /api/events

Manually trigger event processing (useful for testing).

curl -X POST https://bluewireless.azurewebsites.net/api/events \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "partitionKey": "ACC-2847",
    "rowKey": "2024-01-15T14:32:00Z",
    "eventType": "outage",
    "severity": 2,
    "affectedServices": ["voip", "data"],
    "customerImpact": 1200,
    "description": "Complete service outage in Northeast region"
  }'

GET /api/health

Health check endpoint. Returns status of all integrated services.

{
  "status": "healthy",
  "services": {
    "azure_storage": { "status": "up", "latency_ms": 45 },
    "zendesk": { "status": "up", "latency_ms": 142 },
    "provider_a": { "status": "up", "latency_ms": 89 },
    "provider_b": { "status": "degraded", "latency_ms": 1240 },
    "ai_model": { "status": "up", "latency_ms": 230 }
  }
}