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
This commit is contained in:
movingsam
parent
da4f03502a
commit
b420ca1f1b
82
.planning/PROJECT.md
Normal file
82
.planning/PROJECT.md
Normal file
@ -0,0 +1,82 @@
|
||||
# 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*
|
||||
90
.planning/REQUIREMENTS.md
Normal file
90
.planning/REQUIREMENTS.md
Normal file
@ -0,0 +1,90 @@
|
||||
# Requirements: Fengling Gateway
|
||||
|
||||
**Defined:** 2026-03-02
|
||||
**Core Value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates.
|
||||
|
||||
## v1 Requirements
|
||||
|
||||
Requirements for initial release. Each maps to roadmap phases.
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- [ ] **CFG-01**: Gateway listens to config change events from fengling-console
|
||||
- [ ] **CFG-02**: Gateway reloads configuration without restart when notified
|
||||
- [ ] **CFG-03**: Multi-instance gateway receives config updates via broadcast (Redis pub/sub or PostgreSQL NOTIFY)
|
||||
|
||||
### Multi-Instance Support
|
||||
|
||||
- [ ] **INST-01**: Multiple gateway instances can run simultaneously
|
||||
- [ ] **INST-02**: Configuration changes propagate to all instances
|
||||
- [ ] **INST-03**: Redis-based pub/sub for cross-instance communication
|
||||
|
||||
### K8s Health Delegation
|
||||
|
||||
- [ ] **K8S-01**: Remove K8s health monitoring from gateway
|
||||
- [ ] **K8S-02**: Gateway delegates service health checks to console
|
||||
|
||||
### Security Fixes
|
||||
|
||||
- [ ] **SEC-01**: Remove hardcoded credentials from source code
|
||||
- [ ] **SEC-02**: Implement proper JWT token validation
|
||||
- [ ] **SEC-03**: Add authentication to gateway management API endpoints
|
||||
|
||||
### Performance
|
||||
|
||||
- [ ] **PERF-01**: Optimize load balancing lock contention
|
||||
- [ ] **PERF-02**: Implement incremental route cache updates
|
||||
|
||||
## v2 Requirements
|
||||
|
||||
Deferred to future release. Tracked but not in current roadmap.
|
||||
|
||||
### Observability
|
||||
|
||||
- **OBS-01**: Distributed tracing integration
|
||||
- **OBS-02**: Custom metrics for gateway performance
|
||||
|
||||
### Testing
|
||||
|
||||
- **TEST-01**: Unit tests for RouteCache
|
||||
- **TEST-02**: Unit tests for JwtTransformMiddleware
|
||||
- **TEST-03**: Unit tests for load balancing policy
|
||||
|
||||
## Out of Scope
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Direct gateway configuration UI | Handled by fengling-console |
|
||||
| K8s service health checks in gateway | Delegated to console |
|
||||
| Authentication logic in gateway | Handled by auth-service |
|
||||
| Authorization logic in gateway | Handled by downstream services |
|
||||
|
||||
## Traceability
|
||||
|
||||
Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| CFG-01 | Phase 1 | Pending |
|
||||
| CFG-02 | Phase 1 | Pending |
|
||||
| CFG-03 | Phase 1 | Pending |
|
||||
| INST-01 | Phase 1 | Pending |
|
||||
| INST-02 | Phase 1 | Pending |
|
||||
| INST-03 | Phase 1 | Pending |
|
||||
| K8S-01 | Phase 2 | Pending |
|
||||
| K8S-02 | Phase 2 | Pending |
|
||||
| SEC-01 | Phase 3 | Pending |
|
||||
| SEC-02 | Phase 3 | Pending |
|
||||
| SEC-03 | Phase 3 | Pending |
|
||||
| PERF-01 | Phase 4 | Pending |
|
||||
| PERF-02 | Phase 4 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: 12 total
|
||||
- Mapped to phases: 12
|
||||
- Unmapped: 0 ✓
|
||||
|
||||
---
|
||||
|
||||
*Requirements defined: 2026-03-02*
|
||||
*Last updated: 2026-03-02 after initial definition*
|
||||
106
.planning/ROADMAP.md
Normal file
106
.planning/ROADMAP.md
Normal file
@ -0,0 +1,106 @@
|
||||
# Roadmap: Fengling Gateway
|
||||
|
||||
**Created:** 2026-03-02
|
||||
**Core Value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Console-Driven Configuration & Multi-Instance Support
|
||||
|
||||
**Goal:** Implement console-driven configuration management and multi-instance support.
|
||||
|
||||
**Requirements:**
|
||||
- CFG-01: Gateway listens to config change events from fengling-console
|
||||
- CFG-02: Gateway reloads configuration without restart when notified
|
||||
- CFG-03: Multi-instance gateway receives config updates via broadcast
|
||||
- INST-01: Multiple gateway instances can run simultaneously
|
||||
- INST-02: Configuration changes propagate to all instances
|
||||
- INST-03: Redis-based pub/sub for cross-instance communication
|
||||
|
||||
**Success Criteria:**
|
||||
1. Gateway can subscribe to config change events from console
|
||||
2. Configuration reload works without gateway restart
|
||||
3. Multiple gateway instances stay synchronized
|
||||
4. Broadcast events reach all instances within 5 seconds
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: K8s Health Delegation
|
||||
|
||||
**Goal:** Remove K8s health monitoring from gateway, delegate to console.
|
||||
|
||||
**Requirements:**
|
||||
- K8S-01: Remove K8s health monitoring from gateway
|
||||
- K8S-02: Gateway delegates service health checks to console
|
||||
|
||||
**Success Criteria:**
|
||||
1. KubernetesPendingSyncService is deprecated/removed from gateway
|
||||
2. Health check logic moved to console project
|
||||
3. Gateway only performs request routing, not health monitoring
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Security Hardening
|
||||
|
||||
**Goal:** Fix critical security vulnerabilities.
|
||||
|
||||
**Requirements:**
|
||||
- SEC-01: Remove hardcoded credentials from source code
|
||||
- SEC-02: Implement proper JWT token validation
|
||||
- SEC-03: Add authentication to gateway management API endpoints
|
||||
|
||||
**Success Criteria:**
|
||||
1. No hardcoded passwords/secrets in source code
|
||||
2. JWT tokens are validated (signature, expiration, issuer, audience)
|
||||
3. All /api/gateway/* endpoints require authentication
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Performance Optimization
|
||||
|
||||
**Goal:** Optimize gateway performance under high load.
|
||||
|
||||
**Requirements:**
|
||||
- PERF-01: Optimize load balancing lock contention
|
||||
- PERF-02: Implement incremental route cache updates
|
||||
|
||||
**Success Criteria:**
|
||||
1. Load balancing does not require per-request Redis lock
|
||||
2. Route cache updates are incremental, not full reload
|
||||
3. Gateway handles 10x more requests per second
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Observability & Testing
|
||||
|
||||
**Goal:** Add observability and test coverage.
|
||||
|
||||
**Requirements:**
|
||||
- OBS-01: Distributed tracing integration
|
||||
- OBS-02: Custom metrics for gateway performance
|
||||
- TEST-01: Unit tests for RouteCache
|
||||
- TEST-02: Unit tests for JwtTransformMiddleware
|
||||
- TEST-03: Unit tests for load balancing policy
|
||||
|
||||
**Success Criteria:**
|
||||
1. Distributed traces include gateway spans
|
||||
2. Key metrics are exported (request count, latency, error rate)
|
||||
3. Core components have >80% test coverage
|
||||
|
||||
---
|
||||
|
||||
## Roadmap Summary
|
||||
|
||||
| Phase | Name | Requirements | Status |
|
||||
|-------|------|--------------|--------|
|
||||
| 1 | Console-Driven Config & Multi-Instance | 6 | Not planned |
|
||||
| 2 | K8s Health Delegation | 2 | Not planned |
|
||||
| 3 | Security Hardening | 3 | Not planned |
|
||||
| 4 | Performance Optimization | 2 | Not planned |
|
||||
| 5 | Observability & Testing | 5 | Not planned |
|
||||
|
||||
**Total:** 5 phases | 18 requirements | All covered ✓
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-03-02 after roadmap creation*
|
||||
75
.planning/STATE.md
Normal file
75
.planning/STATE.md
Normal file
@ -0,0 +1,75 @@
|
||||
# State: Fengling Gateway
|
||||
|
||||
**Last Updated:** 2026-03-02
|
||||
|
||||
---
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-03-02)
|
||||
|
||||
**Core value:** Reliable, scalable API gateway that distributes traffic to backend microservices with zero-downtime configuration updates.
|
||||
|
||||
**Current focus:** Phase 1: Console-Driven Configuration & Multi-Instance Support
|
||||
|
||||
---
|
||||
|
||||
## Project State
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| PROJECT.md | ✓ Initialized |
|
||||
| config.json | ✓ Created |
|
||||
| Requirements | ✓ Defined (18 requirements) |
|
||||
| Roadmap | ✓ Created (5 phases) |
|
||||
| Research | Not started (auto mode skipped) |
|
||||
|
||||
---
|
||||
|
||||
## Phase Status
|
||||
|
||||
| Phase | Name | Status | Plans | Progress |
|
||||
|-------|------|--------|-------|----------|
|
||||
| 1 | Console-Driven Config & Multi-Instance | Not planned | 0 | 0% |
|
||||
| 2 | K8s Health Delegation | Not planned | 0 | 0% |
|
||||
| 3 | Security Hardening | Not planned | 0 | 0% |
|
||||
| 4 | Performance Optimization | Not planned | 0 | 0% |
|
||||
| 5 | Observability & Testing | Not planned | 0 | 0% |
|
||||
|
||||
---
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Initialization
|
||||
|
||||
- **2026-03-02:** Project initialized via /gsd-new-project --auto
|
||||
- Brownfield project with existing codebase (ARCHITECTURE.md, CONCERNS.md, STACK.md existed)
|
||||
- User provided context: gateway architecture discussion with focus on console-driven config
|
||||
|
||||
### Key Decisions
|
||||
|
||||
| Decision | Date | Notes |
|
||||
|----------|------|-------|
|
||||
| Console-driven config | 2026-03-02 | Config changes in fengling-console, gateway listens |
|
||||
| Multi-instance via broadcast | 2026-03-02 | Redis pub/sub or PostgreSQL NOTIFY |
|
||||
| K8s health delegation | 2026-03-02 | Console handles K8s health, not gateway |
|
||||
|
||||
### Roadmap Evolution
|
||||
|
||||
- Phase 1 added: Console-Driven Configuration & Multi-Instance Support
|
||||
- Phase 2 added: K8s Health Delegation
|
||||
- Phase 3 added: Security Hardening
|
||||
- Phase 4 added: Performance Optimization
|
||||
- Phase 5 added: Observability & Testing
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Auto mode: research skipped, workflow preferences set to yolo
|
||||
- Config changes should be committed to git (commit_docs: true)
|
||||
- gsd-tools.cjs not available - project structure created manually
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-03-02 after initialization*
|
||||
13
.planning/config.json
Normal file
13
.planning/config.json
Normal file
@ -0,0 +1,13 @@
|
||||
{
|
||||
"mode": "yolo",
|
||||
"depth": "standard",
|
||||
"parallelization": true,
|
||||
"commit_docs": true,
|
||||
"model_profile": "balanced",
|
||||
"workflow": {
|
||||
"research": false,
|
||||
"plan_check": false,
|
||||
"verifier": false,
|
||||
"auto_advance": true
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user