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