movingsam b420ca1f1b docs: initialize project - gateway architecture planning

- Add PROJECT.md with core value and requirements
- Add config.json with yolo workflow preferences
- Add REQUIREMENTS.md with 18 v1 requirements
- Add ROADMAP.md with 5 phases
- Add STATE.md with project memory

2026-03-02 18:12:23 +08:00

3.2 KiB

Raw Blame History

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

3.2 KiB Raw Blame History