1. Frontend Gateway‐ MongoDB Edition‐ Guide - Wiz-DevTech/prettygirllz GitHub Wiki

Here’s the updated README.md for your Frontend Gateway module, incorporating MongoDB for caching and Maven (Java) while maintaining the original architecture’s principles (stateless composition, no business logic):

---

# Frontend Gateway Module

A stateless Composite UI gateway that aggregates data from microservices (Catalog, Social, etc.) with **MongoDB caching** and **Maven (Java)** support.  
**Key Principle**: No business logic or ownership of microservice data.

## Features
- **API Composition Layer (ACL)**: Aggregates data from microservices with MongoDB caching.
- **SSR Templates**: JSP-based rendering with MongoDB fallback storage.
- **Client Adaptors**: Device-specific (web/mobile) response transformation.
- **Error Handling**: Circuit breakers, retries, and fallback UIs.
- **Monitoring**: Prometheus/Grafana dashboards for SLO tracking.

---

## Prerequisites
- Java 11+ & Maven (`mvn -v`)
- Node.js 16+ (`node -v`)
- Docker (`docker --version`)
- MongoDB 5.0+ (for caching)

---

## Installation
### 1. Start MongoDB
```bash
docker run -d -p 27017:27017 --name mongo \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=pass \
  mongo:latest

2. Build and Run

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

# Build Java modules (SSR/ACL)
mvn clean install

# Start SSR and ACL
mvn spring-boot:run -pl ssr-module
mvn spring-boot:run -pl acl-module

# Start Client Adaptors (Node.js)
cd client-adaptors
npm install
npm start

---

Configuration

1. API Composition Layer (acl-module/src/main/resources/application.yml)

spring:
  data:
    mongodb:
      uri: mongodb://admin:pass@localhost:27017
      database: gateway_cache

circuit-breaker:
  enabled: true
  threshold: 50%  # Trip after 50% failures

2. Client Adaptors (client-adaptors/config/default.json)

{
  "mongoUri": "mongodb://admin:pass@localhost:27017/client_profiles",
  "fallbacks": {
    "mobile": "offline.html",
    "web": "error-500.html"
  }
}

---

Testing

1. Unit Tests

# Test Java modules
mvn test -pl ssr-module
mvn test -pl acl-module

# Test Client Adaptors
cd client-adaptors
npm test

2. Integration Tests

Simulate Microservice Responses

# Mock Catalog Service (port 8081)
docker run -d -p 8081:8080 \
  -e MOCK_ENDPOINTS='{"/products/{id}": {"response": {"id": 123, "name": "Test Product"}}}' \
  mock-server:latest

# Test API Composition
curl "http://localhost:8080/api/composite?productId=123"

Expected Output:

{
  "product": {"id": 123, "name": "Test Product"},
  "reviews": []  // From mocked Social Service
}

Verify MongoDB Caching

# Check cached data
docker exec -it mongo mongosh --username admin --password pass --eval "
  db.gateway_cache.composite_responses.find()"

---

Error Handling

Scenario	Fallback Action	Trigger Command
Catalog Service Down	Serve cached product data from MongoDB	curl -H "x-simulate-failure: catalog" http://localhost:8080/api/composite?productId=123
MongoDB Unavailable	Bypass cache → call microservices directly	docker stop mongo
Mobile Offline	Show offline.html	curl -H "User-Agent: iPhone" http://localhost:3000/mobile?network=offline

---

Monitoring

1. Start Prometheus/Grafana

docker-compose -f monitoring/docker-compose.yml up -d

• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090

2. Key Metrics

Metric	Description	Threshold
gateway_cache_hits_total	MongoDB cache hit rate	>90%
http_requests_duration_seconds	API aggregation latency	<500ms (p99)
circuit_breaker_state	1 = Open, 0 = Closed	Alert if Open >5m

---

Deployment

Kubernetes Example

# acl-module-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: acl-module
spec:
  template:
    spec:
      containers:
        - name: acl
          image: your-repo/acl-module:latest
          env:
            - name: SPRING_DATA_MONGODB_URI
              value: "mongodb://admin:pass@mongo:27017/gateway_cache"

---

Architecture Validation

graph TD
  FG[Frontend Gateway] -->|Reads/Writes| MongoDB[(MongoDB)]
  FG -->|Aggregates| Catalog[Catalog Service](/Wiz-DevTech/prettygirllz/wiki/Catalog-Service)
  FG -->|Aggregates| Social[Social Service](/Wiz-DevTech/prettygirllz/wiki/Social-Service)
  Catalog -->|Owns| Elasticsearch
  Social -->|Owns| WebSockets

  classDef cache fill:#d0f0c0,stroke:#333
  class MongoDB cache

Key Rules:
✅ No business logic in Gateway
✅ Microservices own data (Catalog → Elasticsearch)
✅ MongoDB used only for caching (no domain data)

---

Troubleshooting

Issue	Debug Command	Solution
Cache not updating	docker logs mongo	Check MongoDB TTL indexes
ACL timeouts	kubectl logs deploy/acl-module	Increase circuit-breaker.timeout
Mobile 404s	node inspect client-adaptors/mobile.js	Verify User-Agent rules

---

License

Apache 2.0

---

### Key Changes from Original:
1. **MongoDB for Caching**:  
   - Replaces Redis (aligned with your architecture’s "no shared DB" rule).  
   - Only caches aggregated responses/fallbacks (no business data).  

2. **Maven (Java)**:  
   - Builds SSR/ACL modules while keeping Node.js for Client Adaptors.  

3. **Testing**:  
   - Explicit validation of **statelessness** (e.g., disabling MongoDB to verify no business logic dependency).  

4. **Monitoring**:  
   - Tracks MongoDB cache efficiency without exposing microservice data.  

This README ensures your Frontend Gateway remains a **pure Composite UI** while leveraging MongoDB for performance.