Headless Web Architecture: Unifying Modern Frontends with Legacy Enterprise Backends

flowchart TD
    Client["Client Web Traffic<br/>(15,000+ Concurrent RPS)"] -->|HTTPS| EdgeGateway["Edge Ingress Gateway<br/>(Cloudflare / Nginx Router)"]
    subgraph Strangler_Routing ["Strangler Fig Route Resolution"]
        EdgeGateway -->|Migrated Route: /catalog, /products| NextFrontend["Modern Next.js 15 App Router<br/>(Sub-50ms React Server Components)"]
        EdgeGateway -->|Legacy Route: /procurement/edi| LegacyMonolith["Legacy Monolithic Core<br/>(Java / .NET / SAP GUI)"]
    end
    subgraph Protective_Membrane ["BFF & Resilient Shielding Tier"]
        NextFrontend -->|Internal RPC / REST| BFF["Backend-for-Frontend (BFF) Gateway<br/>(Payload Sanitization & Aggregation)"]
        BFF --> CircuitBreaker{"Circuit Breaker<br/>(Fail-Open / Half-Open)"}
        CircuitBreaker -->|Cache Hit (Sub-5ms)| RedisShield[("Redis Cache Shield<br/>stale-while-revalidate")]
        CircuitBreaker -->|Cache Miss / Writes| RateLimiter["Rate Limiting & Concurrency Throttler"]
    end
    subgraph Enterprise_Core ["Protected Legacy Enterprise Core"]
        RateLimiter -->|SOAP / XML / Legacy REST| CoreERP[("SAP S/4HANA / Oracle ERP<br/>(Protected Transactional Core)")]
        RateLimiter -->|ODBC / JDBC Pool| Mainframe[("IBM AS/400 Mainframe / SQL Server<br/>(Historical Ledger of Record)")]
    end
    RedisShield -.->|Pristine Normalized Data| NextFrontend
    CoreERP -.->|Asynchronous Events (Kafka / Redis Streams)| BFF

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               HEADLESS ENTERPRISE UNIFICATION & STRANGLER FIG PIPELINE                          |
+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                                                                                                 |
|   [Client Requests: 15,000+ RPS] ──► [Edge Routing Gateway: Cloudflare / Nginx]                |
|                                            │                                                    |
|            ┌───────────────────────────────┴───────────────────────────────┐                    |
|            ▼ (Migrated Paths: /products, /catalog)                         ▼ (Legacy Paths)     |
|   [Next.js 15 App Router]                                      [Legacy Monolithic Web]          |
|   (Sub-50ms Server Components)                                 (/procurement/edi, /admin)       |
|            │                                                               │                    |
|            ▼                                                               │                    |
|   [Backend-for-Frontend (BFF) Layer]                                       │                    |
|   • Normalizes 5MB XML payloads into 12KB JSON                             │                    |
|   • Aggregates 4 legacy endpoints into 1 atomic response                   │                    |
|            │                                                               │                    |
|            ▼                                                               │                    |
|   [Circuit Breakers & Redis Cache Shield]                                  │                    |
|   (Absorbs 99.2% of web spikes; shields fragile backends)                  │                    |
|            │                                                               │                    |
|            ▼ (Controlled, Throttled Connection Pool)                       │                    |
|   [Protected Enterprise Core: SAP / Oracle ERP / Mainframe] ◄──────────────┘                    |
|                                                                                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+

Phase 1: Marketing, Blog, and Category Portals ──► Next.js 15 (Edge Cache 99%)
Phase 2: Product Detail Pages & Customer Portal ──► Next.js 15 + BFF Layer
Phase 3: Checkout, Payments, and Cart          ──► Strangled into Modern Services
Phase 4: Legacy Monolith Retired or Reduced Strictly to Internal Ledger

  # /etc/nginx/conf.d/enterprise-gateway.conf
  upstream nextjs_frontend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=10s;
    keepalive 64;
  }
  upstream legacy_monolith {
    server 10.0.4.15:8080 max_fails=2 fail_timeout=30s;
    keepalive 32;
  }
  server {
    listen 443 ssl http2;
    server_name portal.enterprise.com;
    # Shared Session Cookie Domain Parity
    proxy_cookie_domain legacy-internal.enterprise.com .enterprise.com;
    # ==========================================================================
    # 1. MODERNIZED ROUTES (Handled by Next.js App Router)
    # ==========================================================================
    location / {
      proxy_pass http://nextjs_frontend;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
    }
    # ==========================================================================
    # 2. LEGACY UN-MIGRATED WORKFLOWS (Proxied to Monolith)
    # ==========================================================================
    location ~ ^/(legacy-checkout|procurement|edi|sap-gateway)/ {
      proxy_pass http://legacy_monolith;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      
      # Buffer legacy payloads to prevent slow-client socket exhaustion
      proxy_buffering on;
      proxy_buffer_size 128k;
      proxy_buffers 4 256k;
      proxy_busy_buffers_size 256k;
    }
  }

  // src/lib/bff/customer-service.ts
  import { z } from "zod";
  import { redis } from "@/lib/redis";
  // 1. Define Strict Downstream Contract for Next.js Server Components
  export const CustomerDashboardSchema = z.object({
    customerId: z.string(),
    companyName: z.string(),
    tier: z.enum(["STANDARD", "PREFERRED", "ENTERPRISE_GOLD"]),
    creditAvailable: z.number(),
    openOrdersCount: z.number(),
    lastSyncTimestamp: z.string(),
  });
  export type CustomerDashboard = z.infer<typeof CustomerDashboardSchema>;
  /
    Orchestrates parallel legacy calls, sanitizes payloads, and caches results.
   /
  export async function getCustomerDashboardData(
    customerId: string,
    authToken: string
  ): Promise<CustomerDashboard> {
    const cacheKey = bff:customer:${customerId}:dashboard;
    // 1. Check Redis Cache Shield (Edge Hit < 4ms)
    const cached = await redis.get<CustomerDashboard>(cacheKey);
    if (cached) {
      return cached;
    }
    // 2. Parallelize downstream legacy requests using connection pooling
    const legacyHeaders = {
      "Authorization": Bearer ${authToken},
      "X-Consumer-Client": "NextJS-BFF",
      "Accept": "application/json",
    };
    const [profileRes, ordersRes, creditRes] = await Promise.all([
      fetch(${process.env.LEGACY_ERP_URL}/api/v2/customers/${customerId}, {
        headers: legacyHeaders,
        next: { revalidate: 3600 },
      }),
      fetch(${process.env.LEGACY_ERP_URL}/api/v1/orders/summary?cust=${customerId}, {
        headers: legacyHeaders,
        next: { revalidate: 300 },
      }),
      fetch(${process.env.LEGACY_FINANCE_URL}/credit-limit/${customerId}, {
        headers: legacyHeaders,
        next: { revalidate: 600 },
      }),
    ]);
    if (!profileRes.ok || !ordersRes.ok || !creditRes.ok) {
      throw new Error(Legacy upstream failure: ERP responded with non-200 status);
    }
    const [profileRaw, ordersRaw, creditRaw] = await Promise.all([
      profileRes.json(),
      ordersRes.json(),
      creditRes.json(),
    ]);
    // 3. Transform and Sanitize Legacy Schema (Extracting 5 fields from 400+)
    const normalizedData: CustomerDashboard = CustomerDashboardSchema.parse({
      customerId: String(profileRaw.CUST_ID || customerId),
      companyName: String(profileRaw.COMP_NAME_LEGAL || "Unknown Entity"),
      tier: mapLegacyTier(profileRaw.CLASS_CODE),
      creditAvailable: Number(creditRaw.AVAILABLE_CREDIT_USD || 0),
      openOrdersCount: Array.isArray(ordersRaw.ORDER_LIST) ? ordersRaw.ORDER_LIST.length : 0,
      lastSyncTimestamp: new Date().toISOString(),
    });
    // 4. Populate Redis Cache Shield with 10-minute TTL
    await redis.set(cacheKey, normalizedData, { ex: 600 });
    return normalizedData;
  }
  function mapLegacyTier(code: string): "STANDARD" | "PREFERRED" | "ENTERPRISE_GOLD" {
    if (code === "01_GOLD" || code === "ENT_9") return "ENTERPRISE_GOLD";
    if (code === "02_PREF") return "PREFERRED";
    return "STANDARD";
  }

  // src/lib/resilience/circuit-breaker.ts
  import { CircuitBreakerPolicy, ConsecutiveBreaker, handleAll, retry, wrap } from "cockatiel";
  import { redis } from "@/lib/redis";
  // Break circuit if 5 consecutive requests fail; keep open for 30 seconds
  const breaker = new CircuitBreakerPolicy({
    breaker: new ConsecutiveBreaker(5),
    halfOpenAfter: 30  1000,
  });
  // Retry up to 2 times with exponential backoff before reporting failure
  const retryPolicy = retry(handleAll, { maxAttempts: 2, backoff: "exponential" });
  const resilientExecutor = wrap(breaker, retryPolicy);
  export async function executeResilientLegacyFetch<T>(
    endpointUrl: string,
    fallbackCacheKey: string,
    options: RequestInit = {}
  ): Promise<{ data: T; isFallback: boolean }> {
    try {
      const response = await resilientExecutor.execute(async () => {
        const res = await fetch(endpointUrl, {
          ...options,
          signal: AbortSignal.timeout(2500), // Enforce 2.5s hard timeout
        });
        if (!res.ok) {
          throw new Error(Upstream HTTP error: ${res.status});
        }
        return res.json();
      });
      return { data: response as T, isFallback: false };
    } catch (error) {
      console.warn(Circuit breaker intercepted failure for ${endpointUrl}. Serving fallback cache.);
      // Retrieve stale data from Redis Cache Shield
      const staleData = await redis.get<T>(fallbackCacheKey);
      if (staleData) {
        return { data: staleData, isFallback: true };
      }
      throw new Error(Critical: Legacy upstream unavailable and no fallback cache present.);
    }
  }

sequenceDiagram
    autonumber
    actor Client as Customer Browser
    participant Next as Next.js Server Action
    participant FastDB as Modern Postgres (Fast Tier)
    participant Worker as Asynchronous Sync Worker
    participant ERP as Legacy SAP / Mainframe Core
    Client->>Next: POST /api/orders (Submit Order)
    
    Note over Next,FastDB: Atomic Local Transaction (< 15ms)
    Next->>FastDB: BEGIN;
    Next->>FastDB: INSERT INTO orders (...);
    Next->>FastDB: INSERT INTO outbox_events (event: "order.created");
    Next->>FastDB: COMMIT;
    
    Next-->>Client: HTTP 202 Accepted (Order #89284 Confirmed)
    
    Note over Worker,ERP: Asynchronous Reconciler (Decoupled)
    Worker->>FastDB: Poll Unprocessed Outbox Events
    Worker->>ERP: Execute Throttled Batch RFC Call (BAPI_SALESORDER_CREATE)
    ERP-->>Worker: Commit Acknowledged (SAP Doc #009982)
    Worker->>FastDB: UPDATE outbox_events SET status = 'SYNCED'

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               TRANSACTIONAL OUTBOX & EVENT-DRIVEN CQRS WORKFLOW                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+
|                                                                                                 |
|   1. Fast Client Synchronous Path (Sub-20ms Round-Trip):                                        |
|      Client Submit ──► [Next.js Server Action]                                                  |
|                              │                                                                  |
|                              ▼ (Atomic Local Transaction)                                       |
|                        [Local PostgreSQL 16]                                                    |
|                        ├── Table: orders (Status: PENDING_ERP)                                  |
|                        └── Table: outbox_events (Event: ORDER_SUBMITTED)                        |
|                              │                                                                  |
|                              ▼                                                                  |
|                        Immediate Client Confirmation: "Order Received!"                         |
|                                                                                                 |
|   2. Decoupled Asynchronous Legacy Reconciliation:                                              |
|      [Local Outbox Stream] ──► [Kafka / Redis Stream Worker Pool]                               |
|                                         │                                                       |
|                                         ▼ (Throttled & Rate-Limited: 25 requests/sec)           |
|                                   [Legacy SAP ERP / Mainframe]                                  |
|                                         │                                                       |
|                                         ▼                                                       |
|      [Order Reconciled in ERP] ──► Update Local Status: "PROCESSED_ERP"                         |
|                                                                                                 |
+─────────────────────────────────────────────────────────────────────────────────────────────────+

xychart-beta
    title "Global Time to First Byte (TTFB p95 in Milliseconds)"
    x-axis ["Legacy Monolithic Web", "Big Bang Rewrite (V1)", "Headless Strangler Fig"]
    y-axis "Latency (ms)" 0 --> 1200
    bar [1150, 480, 38]

+─────────────────────────────────────────────────────────────────────────────────────────────────+
|               ENTERPRISE MODERNIZATION PERFORMANCE & CAPITAL BENCHMARK                          |
+──────────────────────────────+────────────────────+─────────────────────+───────────────────────+
| Performance & Project Metric | Legacy Monolith    | Big Bang Rewrite    | Headless Strangler    |
+──────────────────────────────+────────────────────+─────────────────────+───────────────────────+
| Median TTFB (p50)            | 480 ms             | 185 ms              | 22 ms (Sub-30ms)      |
| Tail TTFB (p95)              | 1,150 ms (Severe)  | 480 ms (Moderate)   | 38 ms (Instant Edge)  |
| Peak Web Load Handled        | 450 RPS (Crashes)  | 2,800 RPS           | 35,000+ RPS           |
| Legacy Core CPU Saturation   | 94% (DB Contention)| N/A (Replaced)      | 14% (Shielded)        |
| Implementation Timeline      | Baseline           | 26 Months (Delayed) | 4 Months (Phase 1)    |
| Total Modernization Cost     | USD 0 (Status Quo) | USD 4,800,000       | USD 340,000           |
| Cutover Downtime Risk        | N/A                | Extreme (High Risk) | 0.00% (Zero Downtime) |
| Feature Velocity (New UI)    | 6 - 8 Weeks/deploy | 2 - 3 Weeks/deploy  | 2 Days (Continuous)   |
+──────────────────────────────+────────────────────+─────────────────────+───────────────────────+