# Fengling Gateway

## What This Is

API Gateway based on YARP (Yet Another Reverse Proxy) for the Fengling microservice ecosystem. Routes incoming requests to downstream services (auth-service, member-service, activity, platform, risk-control, etc.) with multi-tenant support, dynamic configuration, and distributed load balancing.

## Core Value

Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates.

## Requirements

### Validated

- ✓ Multi-tenant routing based on URL path — existing
- ✓ JWT token parsing and tenant claim extraction — existing
- ✓ Dynamic route configuration from PostgreSQL — existing
- ✓ Service discovery integration with Kubernetes — existing
- ✓ Weighted round-robin load balancing — existing
- ✓ Configuration hot-reload via PostgreSQL NOTIFY — existing

### Active

- [ ] Implement console-driven configuration management (config changes in fengling-console, gateway listens and reloads)
- [ ] Support multiple gateway instances via broadcast events (multi-instance deployment)
- [ ] Remove K8s health monitoring from gateway (delegate to console)

### Out of Scope

- [Direct gateway configuration UI] — Handled by fengling-console
- [K8s service health checks in gateway] — Delegated to console
- [Authentication/Authorization logic] — Handled by auth-service

## Context

**Ecosystem Structure:**
```
fengling-gateway/          # Current project - API Gateway (YARP)
  ↓ routes traffic to:
fengling-console/           # Central management console - config, tenant management
fengling-console-web/      # Web UI for console
fengling-auth-service/      # Authentication service
fengling-member-service/   # Member management
fengling-activity/         # Activity service
fengling-platform/         # Platform service
fengling-risk-control/     # Risk control service
fengling-service-discovery/# Service discovery
```

**Architecture Decision (New):**
- Gateway configuration managed by fengling-console, not directly
- Console publishes config changes → Gateway subscribes and reloads
- Multi-instance support via broadcast (Redis pub/sub or PostgreSQL NOTIFY)
- Console responsible for all K8s service health monitoring
- Gateway only handles request routing

**Current Issues (from CONCERNS.md):**
- Hardcoded credentials (security risk)
- JWT token not validated (security risk)
- API endpoints without authentication (security risk)
- Load balancing lock contention
- No unit tests

## Constraints

- **Multi-instance**: Gateway must support running multiple instances simultaneously
- **Hot reload**: Configuration changes without restart
- **Tech stack**: .NET 10.0, YARP, PostgreSQL, Redis
- **Deployment**: Docker + Kubernetes

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Console-driven config | Centralizes management, single source of truth | ✓ Good |
| Broadcast events for multi-instance | Enables horizontal scaling | ✓ Good |
| Delegate K8s health to console | Reduces gateway complexity, console is ops hub | ✓ Good |
| Keep YARP as core | Well-maintained, Microsoft-supported | ✓ Good |

---

*Last updated: 2026-03-02 after initialization*