1. Frontend Gateway‐ step‐by‐step implementation guide** - Wiz-DevTech/prettygirllz GitHub Wiki

Frontend Gateway module, including setup, testing, and monitoring: Here’s a step-by-step implementation guide

Frontend Gateway Implementation Guide

Step 1: Environment Setup

1.1 Prerequisites

  • Hardware: 4GB RAM, 2 vCPUs
  • Software: 
    # Java (SSR/JSP)
sudo apt install openjdk-11-jdk

# Node.js (Client Adaptors)
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install nodejs

# Docker
sudo apt install docker.io docker-compose

1.2 Clone Repository

git clone https://github.com/your-repo/frontend-gateway.git
cd frontend-gateway

Step 2: Backend Setup (SSR & API Composition)

2.1 Build SSR Templates

./gradlew :ssr-module:build  # Build JSP templates

2.2 Configure API Composition Layer

Edit acl-module/src/main/resources/application.yml:

circuit-breaker:
  enabled: true
  threshold: 50%  # Trip after 50% failures
  timeout: 5000ms  # Timeout per API call

2.3 Start Backend Services

# Start Redis (for SSR fallback)
docker run -d -p 6379:6379 redis

# Start ACL Service
./gradlew :acl-module:bootRun

Step 3: Client Adaptors Setup

3.1 Install Dependencies

cd client-adaptors
npm install

3.2 Configure Device Rules

Edit config/web-adaptor.js:

module.exports = {
  fallbackPage: "/error-500.html",  // Shown on API failures
  timeout: 3000  // 3-second timeout
};

3.3 Start Client Adaptors

npm run start  # Starts web (port 3000) and mobile (port 3001) adaptors

Step 4: Error Handling & Monitoring

4.1 Start Monitoring Stack

docker-compose -f monitoring/docker-compose.yml up -d
  • Grafana: http://localhost:3000 (Default creds: admin/admin)
  • Prometheus: http://localhost:9090
  • ELK: http://localhost:5601

4.2 Configure Alerts

Edit monitoring/prometheus/alert.rules:

- alert: HighErrorRate
  expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
  for: 10m
  labels:
    severity: critical
  annotations:
    summary: "High 5xx error rate ({{ $value }}%)"

Step 5: Testing

5.1 Simulate Failures

# Trigger 500 errors (SSR fallback test)
curl -H "Accept: text/html" http://localhost:8080?simulate_error=500

# Test mobile adaptor offline mode
curl -H "User-Agent: iPhone" http://localhost:3001?network=offline

5.2 Verify Recovery

  1. Circuit Breaker Trip:

    watch -n 1 'curl -s http://localhost:8080/actuator/health | jq .circuitBreakers'

    Expected output when tripped:

    { "status": "OPEN", "failures": 52% }

  2. Fallback UI: Open http://localhost:3000 in browser while mocking API failures:

    docker run -p 1080:1080 mockserver/mockserver -serverPort 1080 -mockInitializersJsonPath /mocks/500-errors.json

Step 6: Deployment

6.1 Build Docker Images

./gradlew jibDockerBuild  # SSR/ACL
docker build -t client-adaptors ./client-adaptors

6.2 Deploy to Kubernetes

kubectl apply -f k8s/

Sample k8s/deployment.yml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: acl-service
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: acl
          image: acl-service:latest
          ports:
            - containerPort: 8080
          env:
            - name: REDIS_HOST
              value: "redis-service"

Step 7: Validate Production

7.1 Smoke Tests

# Check SSR
curl -I http://production-url/ | grep "200 OK"

# Verify mobile adaptor
curl -H "User-Agent: iPhone" http://production-url/api/mobile

7.2 Monitor Dashboards

  • Grafana: Check Frontend SLOs dashboard for uptime.
  • ELK: Search logs for error_code:500.

Troubleshooting Cheatsheet

Issue Debug Command Fix
SSR cache not updating `redis-cli monitor grep "ssr:cache"`
API aggregation timeout kubectl logs deploy/acl-service Increase acl.timeout in config
Mobile adaptor 404s node inspect client-adaptors/mobile.js Validate User-Agent routing rules

Next Steps

  1. Load Testing:

    k6 run --vus 100 --duration 30s test/load-test.js

  2. Security Hardening:

    • Add rate limiting (acl-module/src/main/java/com/yourpackage/RateLimiter.java).
    • Enable JWT auth for APIs.

  3. CI/CD Pipeline:
    Sample GitHub Actions workflow (.github/workflows/deploy.yml):

    jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: ./gradlew build && docker-compose push

This guide covers end-to-end implementation from local setup to production. For advanced scenarios (A/B testing, blue-green deployments), refer to the Advanced Configuration Docs.