Best Practices: Edge Architecture, AI Automation & Modern DevOps

Advanced strategies and proven patterns for building scalable, secure, and high-performance modern applications.

Table of Contents

1. Introduction: Beyond the Basics
2. Edge Architecture Patterns
3. AI Automation Workflows
4. DevOps and CI/CD for Modern Applications
5. Security Best Practices for Edge Applications
6. Performance Optimization Strategies
7. Monitoring and Observability
8. Common Pitfalls and How to Avoid Them
9. Implementation Framework

---

Introduction: Beyond the Basics {#introduction}

Welcome to the advanced guide where we dive deep into the battle-tested strategies and architectural patterns that separate successful implementations from costly failures. This guide is designed for technical leaders, architects, and senior developers who understand the fundamentals and are ready to implement production-grade solutions.

What Makes This Different

Unlike generic tutorials, this guide is based on real-world experience from:

• 100+ production deployments across various industries
• Millions of users served through edge-optimized architectures
• Enterprise-grade security implementations
• Cost-optimized solutions that deliver measurable ROI

Who Should Read This

• CTOs and VPs of Engineering making architectural decisions
• Senior Developers implementing complex systems
• DevOps Engineers building deployment pipelines
• Security Architects designing secure edge applications
• Platform Engineers building internal developer platforms

---

Edge Architecture Patterns {#edge-architecture-patterns}

1. The Global API Gateway Pattern

A centralized entry point that routes requests to the nearest edge location while maintaining consistency.

Architecture Overview

Client DNS → Cloudflare DNS → Nearest Edge Location → API Gateway → Backend Services

Implementation

// Cloudflare Worker as API Gateway
interface RouteConfig {
  path: string;
  service: string;
  version: string;
  cacheTTL?: number;
  auth?: AuthConfig;
  rateLimit?: RateLimitConfig;
}

const routes: RouteConfig[] = [
  {
    path: '/api/v1/users/*',
    service: 'user-service',
    version: 'v1',
    cacheTTL: 300,
    auth: { required: true, roles: ['user', 'admin'] },
    rateLimit: { requests: 100, window: 60 }
  },
  {
    path: '/api/v1/products/*',
    service: 'product-service',
    version: 'v1',
    cacheTTL: 600,
    rateLimit: { requests: 1000, window: 60 }
  }
];

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);
    const route = findMatchingRoute(url.pathname, routes);

    if (!route) {
      return new Response('Not Found', { status: 404 });
    }

    // Authentication
    if (route.auth?.required) {
      const authResult = await authenticate(request, env);
      if (!authResult.valid) {
        return new Response('Unauthorized', { status: 401 });
      }

      // Role-based access control
      if (route.auth.roles && !hasRequiredRole(authResult.user, route.auth.roles)) {
        return new Response('Forbidden', { status: 403 });
      }
    }

    // Rate limiting
    if (route.rateLimit) {
      const rateLimitResult = await checkRateLimit(request, env, route.rateLimit);
      if (!rateLimitResult.allowed) {
        return new Response('Too Many Requests', {
          status: 429,
          headers: {
            'Retry-After': rateLimitResult.retryAfter?.toString() || '60'
          }
        });
      }
    }

    // Caching
    const cacheKey = new Request(request.url, request);
    const cache = caches.default;

    if (route.cacheTTL) {
      const cached = await cache.match(cacheKey);
      if (cached) {
        return cached;
      }
    }

    // Proxy to backend service
    const backendUrl = `${env.BACKEND_BASE_URL}/${route.service}/${route.version}${url.pathname}${url.search}`;

    const response = await fetch(backendUrl, {
      method: request.method,
      headers: request.headers,
      body: request.body
    });

    // Cache successful responses
    if (route.cacheTTL && response.ok) {
      const cachedResponse = new Response(response.body, {
        status: response.status,
        statusText: response.statusText,
        headers: {
          ...response.headers,
          'Cache-Control': `public, max-age=${route.cacheTTL}`,
          'X-Cache': 'HIT'
        }
      });

      ctx.waitUntil(cache.put(cacheKey, cachedResponse.clone()));
      return cachedResponse;
    }

    return response;
  }
};

2. The Hybrid Edge-Cloud Pattern

Combine edge processing for real-time needs with cloud processing for complex operations.

Decision Matrix

Operation	Edge Processing	Cloud Processing
Authentication & Authorization	Fast, distributed	Latency concerns
Request Validation	Immediate feedback	Unnecessary round-trip
Data Aggregation	Simple operations	Complex analytics
Machine Learning Inference	Pre-trained models	Training, fine-tuning
Database Operations	Consistency issues	ACID transactions
File Processing	Small files	Large batch processing

Implementation Example

// Edge Worker for real-time processing
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const startTime = Date.now();
    const url = new URL(request.url);

    try {
      // Edge Processing Layer
      const edgeResult = await processAtEdge(request, env);

      if (edgeResult.canHandle) {
        // Simple operation completed at edge
        return createResponse(edgeResult.data, {
          'X-Processing-Time': `${Date.now() - startTime}ms`,
          'X-Processing-Location': 'edge'
        });
      }

      // Complex operation requires cloud processing
      const cloudResult = await processInCloud(edgeResult.processedData, env);

      return createResponse(cloudResult.data, {
        'X-Processing-Time': `${Date.now() - startTime}ms`,
        'X-Processing-Location': 'hybrid'
      });

    } catch (error) {
      console.error('Processing error:', error);
      return new Response('Internal Server Error', { status: 500 });
    }
  }
};

async function processAtEdge(request: Request, env: Env): Promise<EdgeResult> {
  const data = await request.json();

  // Real-time validation
  const validationResult = validateData(data);
  if (!validationResult.valid) {
    return {
      canHandle: true,
      data: { error: validationResult.errors }
    };
  }

  // Simple business logic
  if (data.operation === 'calculate_shipping') {
    const shipping = calculateShipping(data.weight, data.distance);
    return {
      canHandle: true,
      data: { shipping_cost: shipping },
      processedData: null
    };
  }

  // Complex operation requires cloud processing
  return {
    canHandle: false,
    data: null,
    processedData: data
  };
}

async function processInCloud(data: any, env: Env): Promise<CloudResult> {
  const response = await fetch(`${env.CLOUD_API_URL}/process`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error('Cloud processing failed');
  }

  const result = await response.json();
  return { data: result };
}

3. The Event-Driven Architecture Pattern

Leverage edge computing for real-time event processing and cloud for persistent storage and complex event correlation.

Architecture Components

// Event Schema
interface EdgeEvent {
  id: string;
  type: string;
  source: string;
  timestamp: number;
  data: any;
  metadata: {
    location: string;
    userId?: string;
    sessionId?: string;
  };
}

// Event Processor
class EdgeEventProcessor {
  private eventQueue: EdgeEvent[] = [];
  private batchSize = 10;
  private flushInterval = 1000; // 1 second

  constructor(private env: Env) {
    // Start periodic flush
    setInterval(() => this.flush(), this.flushInterval);
  }

  async processEvent(event: EdgeEvent): Promise<void> {
    // Real-time processing at edge
    await this.handleRealtimeLogic(event);

    // Queue for cloud processing
    this.eventQueue.push(event);

    // Flush if batch size reached
    if (this.eventQueue.length >= this.batchSize) {
      await this.flush();
    }
  }

  private async handleRealtimeLogic(event: EdgeEvent): Promise<void> {
    switch (event.type) {
      case 'user_login':
        await this.updateUserSession(event);
        break;
      case 'product_view':
        await this.updateUserRecommendations(event);
        break;
      case 'cart_update':
        await this.updateInventoryCache(event);
        break;
    }
  }

  private async flush(): Promise<void> {
    if (this.eventQueue.length === 0) return;

    const batch = [...this.eventQueue];
    this.eventQueue = [];

    try {
      // Send batch to cloud for persistent storage
      await fetch(`${env.CLOUD_API_URL}/events/batch`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ events: batch })
      });
    } catch (error) {
      // Re-queue events on failure
      this.eventQueue.unshift(...batch);
      console.error('Failed to flush events:', error);
    }
  }
}

---

AI Automation Workflows {#ai-automation-workflows}

1. Intelligent Content Personalization

Architecture Overview

graph TD
    A[User Request] --> B[Edge Worker]
    B --> C{User Segmented?}
    C -->|No| D[ML Model Inference]
    C -->|Yes| E[Cache Lookup]
    E --> F{Cache Hit?}
    F -->|Yes| G[Return Cached Content]
    F -->|No| H[Generate Personalized Content]
    D --> H
    H --> I[Cache Result]
    I --> G

Implementation

// AI-Powered Content Personalization
class ContentPersonalizer {
  private modelCache = new Map<string, any>();
  private userSegments = new Map<string, UserSegment>();

  constructor(private env: Env) {}

  async personalizeContent(request: Request): Promise<Response> {
    const user = await this.identifyUser(request);
    const userSegment = await this.getUserSegment(user.id);

    // Check cache first
    const cacheKey = `content:${userSegment.type}:${request.url}`;
    const cached = await this.env.CACHE.get(cacheKey, 'json');

    if (cached) {
      return this.createPersonalizedResponse(cached, user);
    }

    // Generate personalized content
    const personalizedContent = await this.generatePersonalizedContent(
      request.url,
      userSegment,
      user
    );

    // Cache for future requests
    await this.env.CACHE.put(
      cacheKey,
      JSON.stringify(personalizedContent),
      { expirationTtl: 300 } // 5 minutes
    );

    return this.createPersonalizedResponse(personalizedContent, user);
  }

  private async generatePersonalizedContent(
    url: string,
    segment: UserSegment,
    user: User
  ): Promise<PersonalizedContent> {
    // Get base content
    const baseContent = await this.getBaseContent(url);

    // Apply personalization rules
    const rules = await this.getPersonalizationRules(segment.type);

    let personalizedContent = { ...baseContent };

    for (const rule of rules) {
      personalizedContent = await this.applyRule(
        personalizedContent,
        rule,
        user,
        segment
      );
    }

    // AI-enhanced personalization
    if (segment.aiPersonalization) {
      const aiEnhancement = await this.enhanceWithAI(
        personalizedContent,
        user,
        segment
      );
      personalizedContent = { ...personalizedContent, ...aiEnhancement };
    }

    return personalizedContent;
  }

  private async enhanceWithAI(
    content: any,
    user: User,
    segment: UserSegment
  ): Promise<any> {
    // Prepare features for AI model
    const features = this.extractFeatures(user, segment, content);

    // Get model inference (running at edge)
    const inference = await this.getModelInference(features);

    // Apply AI recommendations
    return this.applyAIRecommendations(content, inference);
  }

  private async getModelInference(features: number[]): Promise<AIInference> {
    const modelKey = 'personalization_model_v2';

    // Load model if not cached
    if (!this.modelCache.has(modelKey)) {
      const modelData = await this.env.MODEL_BUCKET.get(modelKey);
      if (modelData) {
        const model = await this.loadModel(modelData.body);
        this.modelCache.set(modelKey, model);
      }
    }

    const model = this.modelCache.get(modelKey);
    if (!model) {
      throw new Error('Model not available');
    }

    // Run inference
    return model.predict(features);
  }
}

// Usage in Edge Worker
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const personalizer = new ContentPersonalizer(env);

    if (request.url.includes('/personalized')) {
      return await personalizer.personalizeContent(request);
    }

    return fetch(request);
  }
};

2. Predictive Analytics and Anomaly Detection

Real-time Anomaly Detection

class AnomalyDetector {
  private baselineMetrics: Map<string, BaselineMetric> = new Map();
  private alertThresholds: Map<string, AlertThreshold> = new Map();

  constructor(private env: Env) {
    this.initializeBaselines();
    this.initializeThresholds();
  }

  async analyzeRequest(request: Request): Promise<AnomalyResult> {
    const metrics = await this.extractMetrics(request);
    const anomalies: Anomaly[] = [];

    for (const [key, value] of Object.entries(metrics)) {
      const baseline = this.baselineMetrics.get(key);
      if (!baseline) continue;

      const anomaly = this.detectAnomaly(key, value, baseline);
      if (anomaly) {
        anomalies.push(anomaly);
      }
    }

    // Update baselines with new data
    await this.updateBaselines(metrics);

    // Send alerts if anomalies detected
    if (anomalies.length > 0) {
      await this.sendAlerts(anomalies);
    }

    return {
      isAnomalous: anomalies.length > 0,
      anomalies,
      metrics
    };
  }

  private detectAnomaly(
    metric: string,
    value: number,
    baseline: BaselineMetric
  ): Anomaly | null {
    const threshold = this.alertThresholds.get(metric);
    if (!threshold) return null;

    // Z-score based detection
    const zScore = Math.abs((value - baseline.mean) / baseline.stdDev);

    if (zScore > threshold.zScoreThreshold) {
      return {
        metric,
        value,
        expected: baseline.mean,
        zScore,
        severity: this.calculateSeverity(zScore, threshold),
        timestamp: Date.now()
      };
    }

    return null;
  }

  private async sendAlerts(anomalies: Anomaly[]): Promise<void> {
    const criticalAnomalies = anomalies.filter(a => a.severity === 'critical');

    if (criticalAnomalies.length > 0) {
      // Immediate notification for critical issues
      await fetch(`${env.ALERT_WEBHOOK_URL}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          type: 'critical_anomaly',
          anomalies: criticalAnomalies,
          timestamp: Date.now()
        })
      });
    }

    // Log all anomalies for analysis
    await this.logAnomalies(anomalies);
  }
}

// AI-powered predictive scaling
class PredictiveScaler {
  private trafficHistory: TrafficDataPoint[] = [];
  private model: any;

  async predictTraffic(timeWindow: number): Promise<TrafficPrediction> {
    // Prepare training data
    const trainingData = this.prepareTrainingData();

    // Train/update model if needed
    if (!this.model || this.shouldRetrainModel()) {
      await this.trainModel(trainingData);
    }

    // Make predictions
    const predictions = await this.makePredictions(timeWindow);

    return {
      predictedTraffic: predictions,
      confidence: this.calculateConfidence(predictions),
      recommendations: this.generateRecommendations(predictions)
    };
  }

  private generateRecommendations(predictions: TrafficPrediction[]): string[] {
    const recommendations: string[] = [];
    const peakTraffic = Math.max(...predictions.map(p => p.traffic));
    const currentCapacity = this.getCurrentCapacity();

    if (peakTraffic > currentCapacity * 0.8) {
      recommendations.push('Scale up infrastructure 15 minutes before peak');
      recommendations.push('Pre-warm additional edge locations');
    }

    if (predictions.some(p => p.traffic < currentCapacity * 0.2)) {
      recommendations.push('Consider scaling down during low-traffic periods');
    }

    return recommendations;
  }
}

3. Automated Decision Making

Intelligent Load Balancing

class IntelligentLoadBalancer {
  private healthScores = new Map<string, number>();
  private performanceMetrics = new Map<string, PerformanceMetrics>();

  async selectBackend(request: Request): Promise<string> {
    const availableBackends = await this.getHealthyBackends();

    if (availableBackends.length === 0) {
      throw new Error('No healthy backends available');
    }

    // Multi-factor decision making
    const weights = await this.calculateWeights(availableBackends, request);
    const selected = this.weightedRandomSelection(availableBackends, weights);

    // Update metrics after request
    this.scheduleMetricsUpdate(selected, request);

    return selected;
  }

  private async calculateWeights(
    backends: string[],
    request: Request
  ): Promise<number[]> {
    const weights: number[] = [];

    for (const backend of backends) {
      const health = this.healthScores.get(backend) || 1.0;
      const performance = this.performanceMetrics.get(backend);
      const latency = performance?.averageLatency || 100;
      const throughput = performance?.throughput || 1000;

      // Calculate composite score
      let score = health;

      // Factor in latency (lower is better)
      score *= Math.exp(-latency / 1000);

      // Factor in throughput (higher is better)
      score *= Math.log(throughput / 1000 + 1);

      // Consider request type
      if (this.isCacheableRequest(request)) {
        score *= this.getCacheHitRate(backend);
      }

      weights.push(score);
    }

    return this.normalizeWeights(weights);
  }

  private async updateHealthScores(): Promise<void> {
    const backends = await this.getAllBackends();

    for (const backend of backends) {
      try {
        const healthCheck = await fetch(`${backend}/health`, {
          signal: AbortSignal.timeout(5000)
        });

        const newScore = healthCheck.ok ?
          Math.min(1.0, this.healthScores.get(backend) || 0.5 + 0.1) :
          Math.max(0.0, (this.healthScores.get(backend) || 0.5) - 0.2);

        this.healthScores.set(backend, newScore);
      } catch (error) {
        this.healthScores.set(backend,
          Math.max(0.0, (this.healthScores.get(backend) || 0.5) - 0.1));
      }
    }
  }
}

---

DevOps and CI/CD for Modern Applications {#devops-cicd}

1. GitOps-Based Infrastructure Management

Kubernetes GitOps Example

# kubernetes/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: edge-api
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: edge-api
  template:
    metadata:
      labels:
        app: edge-api
    spec:
      containers:
      - name: edge-api
        image: myregistry/edge-api:{{ .Values.image.tag }}
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: url
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

GitHub Actions Workflow

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Run integration tests
        run: npm run test:integration

      - name: Run security audit
        run: npm audit --audit-level moderate

  build:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=sha

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v4

      - name: Setup kubectl
        uses: azure/setup-kubectl@v3
        with:
          version: 'v1.28.0'

      - name: Configure kubectl
        run: |
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > kubeconfig
          export KUBECONFIG=kubeconfig

      - name: Deploy to Kubernetes
        run: |
          export KUBECONFIG=kubeconfig

          # Update image tag in deployment
          sed -i "s|image:.*edge-api:.*|image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:main|" kubernetes/deployment.yaml

          # Apply manifests
          kubectl apply -f kubernetes/

          # Wait for rollout
          kubectl rollout status deployment/edge-api -n production

          # Verify deployment
          kubectl get pods -n production -l app=edge-api

  security-scan:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:main
          format: 'sarif'
          output: 'trivy-results.sarif'

      - name: Upload Trivy scan results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: 'trivy-results.sarif'

2. Progressive Delivery Strategies

Canary Deployments with Feature Flags

// Feature flag management at edge
class FeatureFlagManager {
  private flags: Map<string, FeatureFlag> = new Map();

  constructor(private env: Env) {
    this.loadFlags();
  }

  async isEnabled(flagName: string, context: FeatureContext): Promise<boolean> {
    const flag = this.flags.get(flagName);
    if (!flag || !flag.enabled) return false;

    // Check percentage rollout
    if (flag.rolloutPercentage < 100) {
      const hash = this.hashContext(context);
      const bucket = hash % 100;
      if (bucket >= flag.rolloutPercentage) {
        return false;
      }
    }

    // Check targeting rules
    if (flag.targetingRules) {
      return this.evaluateTargetingRules(flag.targetingRules, context);
    }

    return true;
  }

  private evaluateTargetingRules(
    rules: TargetingRule[],
    context: FeatureContext
  ): boolean {
    for (const rule of rules) {
      if (this.matchesRule(rule, context)) {
        return rule.enabled;
      }
    }
    return false.enabled || false;
  }

  private matchesRule(rule: TargetingRule, context: FeatureContext): boolean {
    // User ID targeting
    if (rule.userIds && context.userId) {
      return rule.userIds.includes(context.userId);
    }

    // Geographic targeting
    if (rule.countries && context.country) {
      return rule.countries.includes(context.country);
    }

    // Custom attributes
    if (rule.attributes) {
      for (const [key, value] of Object.entries(rule.attributes)) {
        if (context.attributes[key] !== value) {
          return false;
        }
      }
    }

    return true;
  }
}

// Canary deployment controller
class CanaryController {
  async routeRequest(request: Request): Promise<Response> {
    const context = await this.buildContext(request);
    const flagManager = new FeatureFlagManager(this.env);

    // Check if user should get canary version
    const useCanary = await flagManager.isEnabled('new-api-version', context);

    const backendUrl = useCanary ?
      this.env.CANARY_BACKEND_URL :
      this.env.STABLE_BACKEND_URL;

    // Add header for monitoring
    const modifiedRequest = new Request(request, {
      headers: {
        ...request.headers,
        'X-Version': useCanary ? 'canary' : 'stable',
        'X-User-ID': context.userId || 'anonymous'
      }
    });

    return fetch(backendUrl, modifiedRequest);
  }

  async trackMetrics(request: Request, response: Response): Promise<void> {
    const version = request.headers.get('X-Version');
    const userId = request.headers.get('X-User-ID');
    const statusCode = response.status;
    const responseTime = response.headers.get('X-Response-Time');

    // Send metrics to monitoring system
    await fetch(`${env.METRICS_ENDPOINT}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        timestamp: Date.now(),
        version,
        userId,
        statusCode,
        responseTime: parseInt(responseTime || '0'),
        userAgent: request.headers.get('User-Agent')
      })
    });
  }
}

3. Infrastructure as Code Best Practices

Terraform Module Structure

# modules/edge-infrastructure/main.tf
terraform {
  required_version = ">= 1.0"
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

variable "domain_name" {
  type        = string
  description = "Primary domain name"
}

variable "environment" {
  type        = string
  description = "Environment (prod, staging, dev)"
  default     = "prod"
}

variable "worker_config" {
  type = object({
    script_name     = string
    kv_namespaces   = list(string)
    d1_databases    = list(string)
    r2_buckets      = list(string)
  })
  description = "Cloudflare Worker configuration"
}

# Cloudflare Workers
resource "cloudflare_worker_script" "main" {
  name    = "${var.environment}-${var.worker_config.script_name}"
  content = file("${path.module}/workers/${var.worker_config.script_name}.js")

  kv_namespace_bindings {
    name         = "KV_NAMESPACE"
    namespace_id = cloudflare_worker_kv_namespace.main.id
  }

  r2_bucket_bindings {
    name    = "R2_BUCKET"
    bucket_name = cloudflare_r2_bucket.main.name
  }

  d1_database_bindings {
    name    = "D1_DATABASE"
    database_id = cloudflare_d1_database.main.id
  }
}

# KV Namespaces
resource "cloudflare_worker_kv_namespace" "main" {
  title = "${var.environment}-main-kv"
}

# D1 Database
resource "cloudflare_d1_database" "main" {
  name    = "${var.environment}-main-db"
  version = "1"
}

# R2 Bucket
resource "cloudflare_r2_bucket" "main" {
  account_id = var.cloudflare_account_id
  name       = "${var.environment}-main-storage"
}

# DNS Records
resource "cloudflare_record" "api" {
  zone_id = data.cloudflare_zone.main.id
  name    = "api"
  value   = cloudflare_worker_script.main.domains[0]
  type    = "CNAME"
  ttl     = 3600
}

# Custom Domains for Workers
resource "cloudflare_workers_domain" "main" {
  zone_id = data.cloudflare_zone.main.id
  hostname = "${var.worker_config.script_name}.${var.domain_name}"
  service_name = cloudflare_worker_script.main.name
}

Environment Configuration

# environments/prod.tfvars
domain_name = "vantagecraft.dev"
environment = "prod"

worker_config = {
  script_name  = "api-gateway"
  kv_namespaces = ["cache", "sessions", "rate-limits"]
  d1_databases  = ["main-db"]
  r2_buckets    = ["storage", "backups"]
}

# environments/staging.tfvars
domain_name = "staging.vantagecraft.dev"
environment = "staging"

worker_config = {
  script_name  = "api-gateway"
  kv_namespaces = ["cache", "sessions"]
  d1_databases  = ["staging-db"]
  r2_buckets    = ["storage"]
}

---

Security Best Practices for Edge Applications {#security-best-practices}

1. Zero Trust Architecture

Implementation Pattern

// Zero Trust authentication and authorization
class ZeroTrustAuth {
  private jwtVerifier: JWTVerifier;
  private rbacEngine: RBACEngine;

  constructor(private env: Env) {
    this.jwtVerifier = new JWTVerifier(env.JWT_PUBLIC_KEY);
    this.rbacEngine = new RBACEngine(env.RBAC_POLICY_BUCKET);
  }

  async authenticateAndAuthorize(
    request: Request,
    requiredPermissions: string[]
  ): Promise<AuthResult> {
    // Step 1: Verify JWT token
    const token = this.extractToken(request);
    if (!token) {
      return { success: false, reason: 'No token provided' };
    }

    const jwtPayload = await this.jwtVerifier.verify(token);
    if (!jwtPayload) {
      return { success: false, reason: 'Invalid token' };
    }

    // Step 2: Validate token claims
    const validation = await this.validateTokenClaims(jwtPayload, request);
    if (!validation.valid) {
      return { success: false, reason: validation.reason };
    }

    // Step 3: Check permissions
    const hasPermission = await this.rbacEngine.hasPermissions(
      jwtPayload.userId,
      requiredPermissions,
      jwtPayload.roles
    );

    if (!hasPermission) {
      return { success: false, reason: 'Insufficient permissions' };
    }

    // Step 4: Context-aware authorization
    const contextAuth = await this.contextualAuthorization(
      jwtPayload,
      request,
      requiredPermissions
    );

    if (!contextAuth.authorized) {
      return { success: false, reason: contextAuth.reason };
    }

    return {
      success: true,
      user: {
        id: jwtPayload.userId,
        roles: jwtPayload.roles,
        permissions: jwtPayload.permissions
      }
    };
  }

  private async contextualAuthorization(
    user: JWTPayload,
    request: Request,
    requiredPermissions: string[]
  ): Promise<ContextAuthResult> {
    const context = await this.buildRequestContext(request);

    // Time-based restrictions
    if (this.isOutsideBusinessHours(context.timestamp) &&
        !this.hasRole(user.roles, 'admin')) {
      return { authorized: false, reason: 'Outside business hours' };
    }

    // Geographic restrictions
    if (this.isRestrictedLocation(context.geoLocation) &&
        !this.hasRole(user.roles, 'global-access')) {
      return { authorized: false, reason: 'Geographic restriction' };
    }

    // IP-based restrictions
    if (this.isSuspiciousIP(context.clientIP) &&
        !this.hasRole(user.roles, 'admin')) {
      return { authorized: false, reason: 'Suspicious IP address' };
    }

    // Resource-specific restrictions
    for (const permission of requiredPermissions) {
      const resourceRestriction = await this.checkResourceRestriction(
        user.userId,
        permission,
        context.resourceId
      );

      if (!resourceRestriction.allowed) {
        return {
          authorized: false,
          reason: `Resource access denied: ${permission}`
        };
      }
    }

    return { authorized: true };
  }
}

// Rate limiting with intelligent throttling
class IntelligentRateLimiter {
  private userLimits = new Map<string, UserLimit>();
  private globalLimiters = new Map<string, TokenBucket>();

  async checkRateLimit(
    request: Request,
    user?: User
  ): Promise<RateLimitResult> {
    const clientIP = request.headers.get('CF-Connecting-IP') || 'unknown';
    const endpoint = new URL(request.url).pathname;

    // Get rate limit configuration
    const limitConfig = await this.getLimitConfig(endpoint, user);

    // Check different limit types
    const limits = [
      await this.checkGlobalLimit(endpoint, limitConfig),
      await this.checkUserLimit(user?.id, endpoint, limitConfig),
      await this.checkIPLimit(clientIP, endpoint, limitConfig)
    ];

    // Use the most restrictive limit
    const mostRestrictive = limits.reduce((min, current) =>
      current.remaining < min.remaining ? current : min
    );

    // Log rate limit events
    if (mostRestrictive.remaining <= limitConfig.warningThreshold) {
      await this.logRateLimitWarning(request, mostRestrictive);
    }

    return mostRestrictive;
  }

  private async adaptiveRateLimiting(
    endpoint: string,
    currentLoad: number
  ): Promise<number> {
    // Adjust limits based on system load
    const baseLimit = await this.getBaseLimit(endpoint);
    const loadFactor = Math.max(0.1, 1 - (currentLoad / 100));

    return Math.floor(baseLimit * loadFactor);
  }

  private async detectAbuse(request: Request): Promise<AbuseDetectionResult> {
    const features = await this.extractRequestFeatures(request);

    // Use ML model to detect potential abuse
    const abuseScore = await this.calculateAbuseScore(features);

    if (abuseScore > 0.8) {
      return {
        isAbuse: true,
        confidence: abuseScore,
        reason: 'High abuse probability detected',
        action: 'block'
      };
    }

    if (abuseScore > 0.6) {
      return {
        isAbuse: false,
        confidence: abuseScore,
        reason: 'Suspicious activity detected',
        action: 'challenge'
      };
    }

    return {
      isAbuse: false,
      confidence: 1 - abuseScore,
      reason: 'Normal activity',
      action: 'allow'
    };
  }
}

2. Data Protection and Privacy

Encryption at Edge

class EdgeEncryption {
  private keyManager: KeyManager;

  constructor(private env: Env) {
    this.keyManager = new KeyManager(env);
  }

  async encryptSensitiveData(data: any, context: EncryptionContext): Promise<EncryptedData> {
    const key = await this.keyManager.getEncryptionKey(context.keyId);
    const iv = crypto.getRandomValues(new Uint8Array(12));

    // Encrypt data
    const encodedData = new TextEncoder().encode(JSON.stringify(data));
    const encryptedData = await crypto.subtle.encrypt(
      {
        name: 'AES-GCM',
        iv: iv
      },
      key,
      encodedData
    );

    return {
      data: this.arrayBufferToBase64(encryptedData),
      iv: this.arrayBufferToBase64(iv),
      keyId: context.keyId,
      algorithm: 'AES-GCM',
      timestamp: Date.now()
    };
  }

  async decryptSensitiveData(encryptedData: EncryptedData): Promise<any> {
    const key = await this.keyManager.getEncryptionKey(encryptedData.keyId);
    const iv = this.base64ToArrayBuffer(encryptedData.iv);
    const data = this.base64ToArrayBuffer(encryptedData.data);

    const decryptedData = await crypto.subtle.decrypt(
      {
        name: 'AES-GCM',
        iv: iv
      },
      key,
      data
    );

    const jsonString = new TextDecoder().decode(decryptedData);
    return JSON.parse(jsonString);
  }

  // PII redaction for logging
  redactPII(data: any): any {
    const redacted = { ...data };

    const piiFields = [
      'email', 'password', 'creditCard', 'ssn',
      'phoneNumber', 'address', 'fullName'
    ];

    for (const field of piiFields) {
      if (redacted[field]) {
        redacted[field] = this.redactValue(redacted[field]);
      }
    }

    // Handle nested objects
    for (const key in redacted) {
      if (typeof redacted[key] === 'object' && redacted[key] !== null) {
        redacted[key] = this.redactPII(redacted[key]);
      }
    }

    return redacted;
  }

  private redactValue(value: string): string {
    if (value.length <= 4) return '****';
    return value.substring(0, 2) + '****' + value.substring(value.length - 2);
  }
}

// Privacy compliance management
class PrivacyComplianceManager {
  async handleDataSubjectRequest(request: DataSubjectRequest): Promise<ComplianceResult> {
    switch (request.type) {
      case 'access':
        return await this.handleAccessRequest(request);
      case 'deletion':
        return await this.handleDeletionRequest(request);
      case 'rectification':
        return await this.handleRectificationRequest(request);
      case 'portability':
        return await this.handlePortabilityRequest(request);
      default:
        return { success: false, reason: 'Invalid request type' };
    }
  }

  private async handleDeletionRequest(request: DataSubjectRequest): Promise<ComplianceResult> {
    const userId = request.subjectId;
    const deletionLog: DeletionLogEntry[] = [];

    try {
      // Delete from primary database
      const dbResult = await this.deleteFromDatabase(userId);
      deletionLog.push({
        system: 'primary_database',
        status: dbResult.success ? 'success' : 'failed',
        timestamp: Date.now(),
        details: dbResult.details
      });

      // Delete from cache
      const cacheResult = await this.deleteFromCache(userId);
      deletionLog.push({
        system: 'cache',
        status: cacheResult.success ? 'success' : 'failed',
        timestamp: Date.now(),
        details: cacheResult.details
      });

      // Delete from backup systems
      const backupResult = await this.scheduleBackupDeletion(userId);
      deletionLog.push({
        system: 'backup',
        status: 'scheduled',
        timestamp: Date.now(),
        details: backupResult.details
      });

      // Audit log
      await this.logComplianceEvent({
        type: 'data_deletion',
        subjectId: userId,
        status: 'completed',
        details: deletionLog
      });

      return {
        success: true,
        confirmationId: this.generateConfirmationId(),
        details: deletionLog
      };

    } catch (error) {
      await this.logComplianceEvent({
        type: 'data_deletion',
        subjectId: userId,
        status: 'failed',
        error: error.message
      });

      return {
        success: false,
        reason: 'Deletion process failed',
        details: deletionLog
      };
    }
  }
}

---

Performance Optimization Strategies {#performance-optimization}

1. Intelligent Caching Strategies

Multi-layer Caching Architecture

class IntelligentCacheManager {
  private l1Cache: Map<string, CacheEntry> = new Map(); // Memory
  private l2Cache: KVNamespace; // Edge KV
  private l3Cache: R2Bucket; // Object storage

  constructor(private env: Env) {
    this.l2Cache = env.CACHE_KV;
    this.l3Cache = env.CACHE_R2;
  }

  async get(key: string, options: CacheOptions = {}): Promise<any | null> {
    const cacheKey = this.buildCacheKey(key, options);

    // L1 Cache (Memory) - Fastest
    const l1Entry = this.l1Cache.get(cacheKey);
    if (l1Entry && !this.isExpired(l1Entry)) {
      this.promoteKey(cacheKey); // LRU promotion
      return l1Entry.data;
    }

    // L2 Cache (Edge KV) - Fast
    try {
      const l2Data = await this.l2Cache.get(cacheKey, 'json');
      if (l2Data && !this.isExpired(l2Data)) {
        // Promote to L1
        this.l1Cache.set(cacheKey, {
          data: l2Data.data,
          expiry: l2Data.expiry,
          lastAccessed: Date.now()
        });
        return l2Data.data;
      }
    } catch (error) {
      console.error('L2 cache error:', error);
    }

    // L3 Cache (R2) - Slower but larger
    try {
      const l3Object = await this.l3Cache.get(`${cacheKey}.json`);
      if (l3Object) {
        const l3Data = await l3Object.json();
        if (!this.isExpired(l3Data)) {
          // Promote to higher levels
          await this.setHigherLevelCaches(cacheKey, l3Data.data, l3Data.expiry);
          return l3Data.data;
        }
      }
    } catch (error) {
      console.error('L3 cache error:', error);
    }

    return null; // Cache miss
  }

  async set(key: string, data: any, options: CacheOptions = {}): Promise<void> {
    const cacheKey = this.buildCacheKey(key, options);
    const expiry = options.ttl ? Date.now() + (options.ttl * 1000) : 0;

    // Store in all cache layers
    const cacheEntry: CacheEntry = {
      data,
      expiry,
      lastAccessed: Date.now(),
      size: this.calculateSize(data)
    };

    // L1 Cache (Memory)
    if (this.shouldStoreInL1(cacheEntry)) {
      this.manageL1Size(); // Evict if necessary
      this.l1Cache.set(cacheKey, cacheEntry);
    }

    // L2 Cache (Edge KV)
    if (this.shouldStoreInL2(cacheEntry)) {
      await this.l2Cache.put(cacheKey, JSON.stringify(cacheEntry), {
        expirationTtl: options.ttl
      });
    }

    // L3 Cache (R2)
    if (this.shouldStoreInL3(cacheEntry)) {
      await this.l3Cache.put(`${cacheKey}.json`, JSON.stringify(cacheEntry));
    }
  }

  private shouldStoreInL1(entry: CacheEntry): boolean {
    // Store in L1 if small and frequently accessed
    return entry.size < 1024 * 100; // 100KB limit
  }

  private shouldStoreInL2(entry: CacheEntry): boolean {
    // Store in L2 if medium size
    return entry.size < 1024 * 1024; // 1MB limit
  }

  private shouldStoreInL3(entry: CacheEntry): boolean {
    // Store in L3 for larger objects
    return entry.size < 1024 * 1024 * 100; // 100MB limit
  }
}

// Predictive cache warming
class PredictiveCacheWarmer {
  private accessPatterns: Map<string, AccessPattern> = new Map();
  private model: any;

  async analyzeAccessPattern(request: Request): Promise<void> {
    const key = this.extractCacheKey(request);
    const timestamp = Date.now();
    const hour = new Date(timestamp).getHours();
    const dayOfWeek = new Date(timestamp).getDay();

    let pattern = this.accessPatterns.get(key);
    if (!pattern) {
      pattern = {
        key,
        accessCount: 0,
        lastAccess: 0,
        hourlyAccess: new Array(24).fill(0),
        dailyAccess: new Array(7).fill(0),
        seasonalPatterns: {}
      };
      this.accessPatterns.set(key, pattern);
    }

    pattern.accessCount++;
    pattern.lastAccess = timestamp;
    pattern.hourlyAccess[hour]++;
    pattern.dailyAccess[dayOfWeek]++;

    // Predict next access
    const prediction = await this.predictNextAccess(key, pattern);

    // Pre-warm if confidence is high
    if (prediction.confidence > 0.8 && prediction.timeToNextAccess < 300000) { // 5 minutes
      await this.warmCache(key);
    }
  }

  private async predictNextAccess(key: string, pattern: AccessPattern): Promise<AccessPrediction> {
    // Simple time-based prediction
    const currentHour = new Date().getHours();
    const currentDay = new Date().getDay();

    // Calculate probability of access in next hour
    const hourlyProbability = pattern.hourlyAccess[currentHour] / pattern.accessCount;
    const dailyProbability = pattern.dailyAccess[currentDay] / pattern.accessCount;

    const combinedProbability = (hourlyProbability + dailyProbability) / 2;

    // Estimate time to next access based on historical patterns
    const averageInterval = this.calculateAverageInterval(pattern);

    return {
      confidence: combinedProbability,
      timeToNextAccess: averageInterval * (1 - combinedProbability)
    };
  }

  async warmCache(key: string): Promise<void> {
    try {
      // Generate fresh data
      const data = await this.generateFreshData(key);

      // Store in cache with appropriate TTL
      await this.cacheManager.set(key, data, {
        ttl: this.calculateOptimalTTL(key),
        priority: 'high'
      });

      console.log(`Cache warmed for key: ${key}`);
    } catch (error) {
      console.error(`Failed to warm cache for ${key}:`, error);
    }
  }
}

2. Database Optimization

Connection Pooling and Query Optimization

class OptimizedDatabaseManager {
  private connectionPools: Map<string, ConnectionPool> = new Map();
  private queryCache: Map<string, QueryResult> = new Map();

  async executeQuery<T>(
    query: string,
    params: any[] = [],
    options: QueryOptions = {}
  ): Promise<T[]> {
    const cacheKey = this.buildQueryCacheKey(query, params);

    // Check query cache
    if (options.useCache !== false) {
      const cached = this.queryCache.get(cacheKey);
      if (cached && !this.isQueryResultExpired(cached)) {
        return cached.data as T[];
      }
    }

    // Get connection from pool
    const pool = await this.getConnectionPool(options.database);
    const connection = await pool.getConnection();

    try {
      // Execute query with optimization
      const startTime = Date.now();
      const result = await this.executeOptimizedQuery(connection, query, params);
      const executionTime = Date.now() - startTime;

      // Cache successful query results
      if (options.cacheTTL && executionTime < 1000) { // Only cache fast queries
        this.queryCache.set(cacheKey, {
          data: result,
          timestamp: Date.now(),
          executionTime,
          ttl: options.cacheTTL
        });
      }

      // Log slow queries
      if (executionTime > 500) {
        await this.logSlowQuery(query, params, executionTime);
      }

      return result as T[];

    } finally {
      connection.release();
    }
  }

  private async executeOptimizedQuery(
    connection: DatabaseConnection,
    query: string,
    params: any[]
  ): Promise<any[]> {
    // Add query hints based on analysis
    const optimizedQuery = this.addOptimizationHints(query, params);

    // Execute with retry logic for transient failures
    return await this.executeWithRetry(
      connection.query.bind(connection),
      [optimizedQuery, params],
      3
    );
  }

  private addOptimizationHints(query: string, params: any[]): string {
    // Simple query optimization patterns
    let optimizedQuery = query;

    // Add appropriate index hints
    if (query.includes('WHERE') && query.includes('ORDER BY')) {
      optimizedQuery = optimizedQuery.replace(
        'SELECT',
        'SELECT /*+ USE_INDEX */'
      );
    }

    // Add LIMIT for large result sets if not present
    if (!query.includes('LIMIT') && query.includes('SELECT')) {
      // Estimate if this might return many rows
      const shouldAddLimit = this.shouldAddLimit(query);
      if (shouldAddLimit) {
        optimizedQuery += ' LIMIT 1000';
      }
    }

    return optimizedQuery;
  }

  // Batch operations for better performance
  async batchInsert<T>(
    table: string,
    records: T[],
    options: BatchOptions = {}
  ): Promise<BatchResult> {
    const batchSize = options.batchSize || 1000;
    const results: BatchResult[] = [];

    for (let i = 0; i < records.length; i += batchSize) {
      const batch = records.slice(i, i + batchSize);
      const batchResult = await this.executeBatch(table, batch);
      results.push(batchResult);
    }

    return {
      totalRecords: records.length,
      successful: results.reduce((sum, r) => sum + r.successful, 0),
      failed: results.reduce((sum, r) => sum + r.failed, 0),
      details: results
    };
  }

  private async executeBatch<T>(table: string, records: T[]): Promise<BatchResult> {
    const pool = await this.getConnectionPool();
    const connection = await pool.getConnection();

    try {
      await connection.beginTransaction();

      const results = await Promise.allSettled(
        records.map(record =>
          connection.query(
            `INSERT INTO ${table} SET ?`,
            [record]
          )
        )
      );

      const successful = results.filter(r => r.status === 'fulfilled').length;
      const failed = results.filter(r => r.status === 'rejected').length;

      if (failed > 0) {
        await connection.rollback();
        return { successful: 0, failed, records };
      } else {
        await connection.commit();
        return { successful, failed: 0, records };
      }

    } catch (error) {
      await connection.rollback();
      throw error;
    } finally {
      connection.release();
    }
  }
}

---

Monitoring and Observability {#monitoring-observability}

1. Distributed Tracing

OpenTelemetry Implementation

class DistributedTracingManager {
  private tracer: Tracer;

  constructor() {
    this.tracer = trace.getTracer('edge-api-tracer');
  }

  async traceOperation<T>(
    operationName: string,
    operation: (span: Span) => Promise<T>,
    attributes: Record<string, any> = {}
  ): Promise<T> {
    const span = this.tracer.startSpan(operationName, {
      attributes: {
        'service.name': 'edge-api',
        'service.version': process.env.VERSION || 'unknown',
        ...attributes
      }
    });

    try {
      const result = await operation(span);

      span.setAttributes({
        'operation.success': true
      });

      return result;

    } catch (error) {
      span.setAttributes({
        'operation.success': false,
        'error.message': error.message,
        'error.type': error.constructor.name
      });

      span.recordException(error);
      throw error;

    } finally {
      span.end();
    }
  }

  async traceHTTPRequest(request: Request): Promise<Response> {
    const attributes = {
      'http.method': request.method,
      'http.url': request.url,
      'http.user_agent': request.headers.get('User-Agent'),
      'http.remote_addr': request.headers.get('CF-Connecting-IP'),
      'http.cf_ray': request.headers.get('CF-Ray')
    };

    return await this.traceOperation(
      'http_request',
      async (span) => {
        // Add custom attributes
        span.setAttributes({
          'http.scheme': new URL(request.url).protocol,
          'http.host': new URL(request.url).host,
          'http.target': new URL(request.url).pathname + new URL(request.url).search
        });

        // Execute request
        const startTime = Date.now();
        const response = await this.executeRequest(request);
        const duration = Date.now() - startTime;

        // Record response metrics
        span.setAttributes({
          'http.status_code': response.status,
          'http.response_time_ms': duration,
          'http.response_content_length': response.headers.get('Content-Length') || 0
        });

        return response;
      },
      attributes
    );
  }

  async traceDatabaseOperation<T>(
    operation: string,
    query: string,
    params: any[],
    executeOperation: () => Promise<T>
  ): Promise<T> {
    return await this.traceOperation(
      'database_operation',
      async (span) => {
        span.setAttributes({
          'db.operation': operation,
          'db.statement': this.sanitizeQuery(query),
          'db.statement.type': this.getQueryType(query)
        });

        const startTime = Date.now();
        const result = await executeOperation();
        const duration = Date.now() - startTime;

        span.setAttributes({
          'db.duration_ms': duration,
          'db.rows_affected': Array.isArray(result) ? result.length : 1
        });

        return result;
      }
    );
  }

  private sanitizeQuery(query: string): string {
    // Remove sensitive data from query for logging
    return query
      .replace(/('.*?'|".*?")/g, '?') // Replace string literals
      .replace(/\b\d+\b/g, '?'); // Replace numeric literals
  }
}

2. Real-time Metrics and Alerting

Custom Metrics Collection

class MetricsCollector {
  private metrics: Map<string, Metric> = new Map();
  private aggregationRules: Map<string, AggregationRule> = new Map();

  constructor(private env: Env) {
    this.initializeMetrics();
    this.setupAggregationRules();
  }

  recordCounter(name: string, value: number = 1, tags: Record<string, string> = {}): void {
    const key = this.buildMetricKey(name, tags);
    const metric = this.metrics.get(key) || { type: 'counter', value: 0, tags };

    metric.value += value;
    metric.timestamp = Date.now();

    this.metrics.set(key, metric);
  }

  recordGauge(name: string, value: number, tags: Record<string, string> = {}): void {
    const key = this.buildMetricKey(name, tags);

    this.metrics.set(key, {
      type: 'gauge',
      value,
      tags,
      timestamp: Date.now()
    });
  }

  recordHistogram(name: string, value: number, tags: Record<string, string> = {}): void {
    const key = this.buildMetricKey(name, tags);
    const metric = this.metrics.get(key) || {
      type: 'histogram',
      values: [],
      tags,
      count: 0,
      sum: 0
    };

    metric.values.push(value);
    metric.count++;
    metric.sum += value;
    metric.timestamp = Date.now();

    // Keep only last 1000 values to prevent memory leaks
    if (metric.values.length > 1000) {
      metric.values = metric.values.slice(-1000);
    }

    this.metrics.set(key, metric);
  }

  async recordRequestMetrics(request: Request, response: Response, duration: number): Promise<void> {
    const url = new URL(request.url);
    const route = this.extractRoute(url.pathname);

    // Request counters
    this.recordCounter('http_requests_total', 1, {
      method: request.method,
      route,
      status: response.status.toString(),
      status_class: Math.floor(response.status / 100).toString() + 'xx'
    });

    // Response time histogram
    this.recordHistogram('http_request_duration_ms', duration, {
      method: request.method,
      route
    });

    // Response size gauge
    const contentLength = response.headers.get('Content-Length');
    if (contentLength) {
      this.recordGauge('http_response_size_bytes', parseInt(contentLength), {
        method: request.method,
        route
      });
    }

    // Check for alerts
    await this.checkAlerts(route, response.status, duration);
  }

  private async checkAlerts(route: string, status: number, duration: number): Promise<void> {
    // Error rate alert
    if (status >= 500) {
      this.recordCounter('http_server_errors_total', 1, { route });

      const errorRate = await this.calculateErrorRate(route, 300); // Last 5 minutes
      if (errorRate > 0.1) { // 10% error rate
        await this.sendAlert({
          type: 'high_error_rate',
          severity: 'critical',
          route,
          errorRate,
          threshold: 0.1
        });
      }
    }

    // Response time alert
    if (duration > 5000) { // 5 seconds
      this.recordCounter('http_slow_requests_total', 1, { route });

      const avgDuration = await this.calculateAverageDuration(route, 300);
      if (avgDuration > 2000) { // 2 seconds average
        await this.sendAlert({
          type: 'high_response_time',
          severity: 'warning',
          route,
          averageDuration: avgDuration,
          threshold: 2000
        });
      }
    }
  }

  private async calculateErrorRate(route: string, timeWindow: number): Promise<number> {
    const cutoff = Date.now() - (timeWindow * 1000);

    let totalRequests = 0;
    let errorRequests = 0;

    for (const [key, metric] of this.metrics) {
      if (key.includes(`route:${route}`) &&
          metric.type === 'counter' &&
          metric.timestamp > cutoff) {

        if (key.includes('http_requests_total')) {
          totalRequests += metric.value;
        }
        if (key.includes('status_class:5xx')) {
          errorRequests += metric.value;
        }
      }
    }

    return totalRequests > 0 ? errorRequests / totalRequests : 0;
  }

  async sendAlert(alert: Alert): Promise<void> {
    const alertPayload = {
      alertName: `${alert.type}_${alert.route}`,
      severity: alert.severity,
      timestamp: Date.now(),
      details: alert,
      source: 'edge-api'
    };

    try {
      // Send to monitoring system
      await fetch(this.env.ALERT_WEBHOOK_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(alertPayload)
      });

      console.log('Alert sent:', alertPayload);
    } catch (error) {
      console.error('Failed to send alert:', error);
    }
  }
}

---

Common Pitfalls and How to Avoid Them {#common-pitfalls}

1. Cache Invalidation Issues

Problem: Cache Stampede

// BAD: Multiple requests trying to refresh cache simultaneously
async function getDataWithCache(key: string) {
  const cached = await cache.get(key);
  if (!cached) {
    const data = await fetchFromBackend(key);
    await cache.set(key, data);
    return data;
  }
  return cached;
}

// GOOD: Implement cache stampede protection
async function getDataWithCacheProtection(key: string) {
  const cached = await cache.get(key);
  if (cached) {
    return cached;
  }

  // Check if refresh is already in progress
  const refreshKey = `refreshing:${key}`;
  const isRefreshing = await cache.get(refreshKey);

  if (isRefreshing) {
    // Wait for refresh to complete
    return await waitForRefresh(key);
  }

  // Mark as refreshing
  await cache.set(refreshKey, 'true', { ttl: 30 }); // 30 second timeout

  try {
    const data = await fetchFromBackend(key);
    await cache.set(key, data, { ttl: 300 }); // 5 minute cache
    return data;
  } finally {
    await cache.delete(refreshKey);
  }
}

2. Database Connection Leaks

Problem: Not releasing connections properly

// BAD: Connection might not be released on error
async function badDatabaseQuery(query: string) {
  const connection = await pool.getConnection();
  const result = await connection.query(query);
  // If an error occurs here, connection is never released
  connection.release();
  return result;
}

// GOOD: Ensure connection is always released
async function goodDatabaseQuery(query: string) {
  const connection = await pool.getConnection();

  try {
    const result = await connection.query(query);
    return result;
  } finally {
    connection.release(); // Always executed
  }
}

// EVEN BETTER: Use connection pool with automatic timeout
async function robustDatabaseQuery(query: string, timeout = 5000) {
  const connection = await pool.getConnection();
  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Query timeout')), timeout)
  );

  try {
    const result = await Promise.race([
      connection.query(query),
      timeoutPromise
    ]);
    return result;
  } finally {
    connection.release();
  }
}

3. Memory Leaks in Edge Workers

Problem: Accumulating data in global scope

// BAD: Global map grows indefinitely
const globalCache = new Map();

export default {
  async fetch(request, env, ctx) {
    const key = new URL(request.url).searchParams.get('key');
    globalCache.set(key, someLargeData); // Never cleared
    return new Response('OK');
  }
};

// GOOD: Implement proper cleanup
const globalCache = new Map();
const MAX_CACHE_SIZE = 1000;

export default {
  async fetch(request, env, ctx) {
    const key = new URL(request.url).searchParams.get('key');

    // Implement LRU eviction
    if (globalCache.size >= MAX_CACHE_SIZE) {
      const firstKey = globalCache.keys().next().value;
      globalCache.delete(firstKey);
    }

    globalCache.set(key, someLargeData);

    // Set up cleanup on fetch completion
    ctx.waitUntil(
      setTimeout(() => {
        globalCache.delete(key);
      }, 300000) // Clear after 5 minutes
    );

    return new Response('OK');
  }
};

---

Implementation Framework {#implementation-framework}

Phase 1: Assessment and Planning (Weeks 1-2)

Technical Assessment:
□ Current infrastructure analysis completed
□ Performance bottlenecks identified
□ Security vulnerabilities assessed
□ Scalability requirements documented
□ Compliance requirements mapped

Team Readiness:
□ Skills assessment completed
□ Training plan developed
□ Development environment setup
□ Tool selection finalized
□ Deployment strategy defined

Risk Assessment:
□ Technical risks identified and mitigated
□ Business risks documented
□ Rollback procedures defined
□ Monitoring requirements specified
□ Success criteria established

Phase 2: Foundation Implementation (Weeks 3-6)

Infrastructure Setup:
□ Edge computing platform configured
□ Database architecture implemented
□ Caching layers deployed
□ Monitoring system operational
□ Security controls implemented

Core Features:
□ API gateway deployed
□ Authentication system implemented
□ Rate limiting configured
□ Load balancing operational
□ Error handling implemented

Testing:
□ Unit tests completed (target: >90% coverage)
□ Integration tests passing
□ Performance benchmarks met
□ Security tests passed
□ Load testing completed

Phase 3: Advanced Features (Weeks 7-10)

AI Integration:
□ ML models deployed to edge
□ Real-time inference operational
□ Model retraining pipeline active
□ Performance monitoring in place
□ A/B testing framework ready

Advanced Optimization:
□ Predictive caching implemented
□ Intelligent routing active
□ Auto-scaling configured
□ Performance tuning completed
□ Cost optimization implemented

Monitoring and Observability:
□ Distributed tracing active
□ Real-time dashboards operational
□ Alerting rules configured
□ Log aggregation working
□ Performance SLAs defined

Phase 4: Production Readiness (Weeks 11-12)

Final Testing:
□ End-to-end testing completed
□ User acceptance testing passed
□ Security audit completed
□ Performance validation successful
□ Compliance verification passed

Deployment:
□ Production environment ready
□ Migration plan executed
□ Monitoring alerts active
□ Documentation complete
□ Team training completed

Post-Launch:
□ Performance monitoring active
□ User feedback collection
□ Issue tracking and resolution
□ Continuous optimization
□ Regular security reviews

---

Get Expert Help

Implementing these advanced patterns and best practices requires deep expertise and experience. VantageCraft specializes in:

• Edge Architecture Design: Building scalable, high-performance systems
• AI Integration: Implementing intelligent automation and personalization
• Security Implementation: Zero Trust architecture and compliance
• Performance Optimization: Advanced caching and database optimization
• DevOps Automation: CI/CD pipelines and GitOps workflows

Our Expertise

• 100+ Production Deployments: Across various industries and scales
• Enterprise-Grade Security: Compliance and best practices
• Performance Optimization: 40-60% improvement in application performance
• Cost Reduction: 30-50% reduction in infrastructure costs
• Canadian Market Focus: Understanding local business needs

Schedule a Consultation

Email: experts@vantagecraft.dev Phone: (416) 555-0123 Website: www.vantagecraft.dev

What you’ll get:

• 2-hour architecture review with our senior engineers
• Detailed implementation roadmap
• Risk assessment and mitigation strategies
• Technology recommendations tailored to your needs

---

This best practices guide is continuously updated based on real-world implementation experience. Last updated: October 28, 2025

Download the complete guide: Get printable version

Join our community: Connect with other technical leaders implementing modern architectures.