Skip to content

Commit ee6c01d

Browse files
aarora79claude
aarora79
and
claude
authored
Add architectural decision documentation for reverse proxy vs application-layer gateway (#125)
* Implement pre-built container publishing and deployment (#122) - Add GitHub Actions workflow for automated container publishing - Create publish_containers.sh script for manual container publishing - Add docker-compose.prebuilt.yml for fast deployment using pre-built images - Update build_and_run.sh to support --prebuilt option - Add comprehensive documentation for container publishing - Update README.md with improved quick start guide using pre-built images - Fix Docker image reference format issues in prebuilt compose file - Support both personal and organization accounts for Docker Hub/GitHub Resolves #122 - Users can now deploy instantly using pre-built containers * Add prominent 'Get Running Now' link to navigation for instant setup * Fix Keycloak URL resolution for host-based credential generation - Update ingress_oauth.py to prioritize KEYCLOAK_ADMIN_URL for local access - Export Keycloak environment variables in generate_creds.sh for child processes - Update .env.example to use localhost as default REGISTRY_URL - Fix SECRET_KEY in .env.example to be uncommented with security warning This ensures generate_creds.sh works correctly when run from the host machine by using localhost:8080 instead of internal Docker hostname keycloak:8080. * Fix broken link to testing section in README quick start guide * Implement AUTH_PROVIDER environment variable filtering for OAuth providers - Modified get_enabled_providers() to respect AUTH_PROVIDER env variable - Auth server now filters OAuth providers based on .env configuration - Only shows the provider specified in AUTH_PROVIDER (e.g., keycloak) - Added comprehensive error handling and warning messages - Prevents need to rebuild containers when switching auth providers - Provides clear feedback when filtering out enabled providers Fixes issue where both Keycloak and Cognito appeared on login page despite AUTH_PROVIDER=keycloak setting in .env file. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * Remove automatic container publishing GitHub workflow - Deleted .github/workflows/publish-containers.yml - Containers will now only be published manually using scripts/publish_containers.sh - Provides better control over when and how containers are published - Prevents unintended automatic deployments on every push/tag Manual publishing command: ./scripts/publish_containers.sh --dockerhub --version v1.0.0 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * Fix token generation script and add credential redaction - Fixed relative import errors in generate_tokens.py that were causing false failure reports - Added robust import handling with fallback mechanisms for utils module - Implemented credential redaction showing only first 8 characters of sensitive values - Added redaction to both Keycloak token generation and generic OAuth flow - Script now correctly reports "5/5 successful" instead of "0/5 successful" 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * Add architectural comparison documentation - Compare reverse proxy vs tools gateway approaches - Analyze performance, security, maintainability, scaling aspects - Document implementation language considerations - Include ASCII diagrams for both architectures - Related to GitHub issue #124 * Restructure architectural comparison into separate tables - Break down large comparison table into focused sections - Add clear markdown headings for each aspect (Performance, Security, etc.) - Bold key impactful differences like protocol independence and scaling - Improve readability and scanability of architectural trade-offs * Clarify resource isolation and add implementation complexity - Update resource isolation to explain data plane vs health check separation - Add implementation complexity row highlighting state management differences - Emphasize long-term maintenance implications of protocol awareness - Better explain why reverse proxy approach is simpler to maintain * Update title and rename file for clarity - Change title from 'Reverse Proxy vs Tools Gateway' to 'Reverse Proxy vs Application-Layer Gateway' - Rename file to match new title and better reflect architectural decision focus - Clarifies that we're comparing transparent proxy vs application-aware approaches * Add MCP specification evolution burden to implementation challenges - Highlight that application-layer gateway must keep MCP client updated with spec changes - Emphasize ongoing maintenance overhead vs protocol-agnostic reverse proxy approach - Document long-term technical debt implications of protocol coupling --------- Co-authored-by: Claude <[email protected]>
1 parent c93adf9 commit ee6c01d

File tree

1 file changed

+171
-0
lines changed

1 file changed

+171
-0
lines changed

‎docs/architectural-decision-reverse-proxy-vs-application-layer-gateway.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Core Architectural Decision: Reverse Proxy vs Application-Layer Gateway
2+
3+
## Executive Summary
4+
5+
This document discusses two potential architectures that were considered during the design phase of this solution: a **reverse proxy architecture** and an alternative **tools gateway architecture**. We analyze both approaches from multiple perspectives: performance, security, long-term maintainability, scaling, and operational complexity, and explain why the reverse proxy approach was selected.
6+
7+
The reverse proxy approach provides better performance, protocol independence, and allows continued Python development while leveraging Nginx for message routing. The tools gateway approach offers better developer experience and enterprise integration but requires Go/Rust implementation for enterprise performance requirements.
8+
9+
These recommendations are not universal but represent the architectural choices we made while building this system.
10+
11+
## Architecture Overview
12+
13+
### Reverse Proxy Pattern (Current)
14+
15+
```
16+
AI Agent/Coding Assistant
17+
|
18+
| Multiple Endpoints
19+
v
20+
┌─────────────────┐
21+
│ Nginx Gateway │
22+
│ /fininfo/ │ ──auth_request──> Auth Server
23+
│ /mcpgw/ │ │
24+
│ /currenttime/ │ <──auth_headers───────┘
25+
└─────────────────┘
26+
│ │ │
27+
│ │ └─── localhost:8003 (currenttime)
28+
│ └───── localhost:8002 (mcpgw)
29+
└─────── localhost:8001 (fininfo)
30+
│
31+
v
32+
Individual MCP Servers
33+
```
34+
35+
**Key Characteristics:**
36+
- Path-based routing (`/fininfo/`, `/mcpgw/`, etc.)
37+
- Nginx handles auth validation and proxying
38+
- Direct streaming connections to backend servers
39+
- Protocol-agnostic (HTTP, WebSocket, SSE, etc.)
40+
41+
### Tools Gateway Pattern (Alternative)
42+
43+
```
44+
AI Agent/Coding Assistant
45+
|
46+
| Single Endpoint
47+
v
48+
┌─────────────────┐
49+
│ Tools Gateway │ ──auth_request──> Auth Server
50+
│ /mcp │ │
51+
│ (aggregates │ <──auth_headers───────┘
52+
│ all tools) │
53+
└─────────────────┘
54+
│
55+
| Tool routing logic
56+
v
57+
┌─────────────────┐
58+
│ MCP Client Pool │
59+
│ fininfo_* │ ──> localhost:8001 (fininfo)
60+
│ mcpgw_* │ ──> localhost:8002 (mcpgw)
61+
│ currenttime_* │ ──> localhost:8003 (currenttime)
62+
└─────────────────┘
63+
```
64+
65+
**Key Characteristics:**
66+
- Single endpoint with tool aggregation
67+
- Gateway implements MCP protocol parsing
68+
- Connection termination and re-establishment
69+
- Tool name prefixing for disambiguation
70+
71+
## Architectural Comparison
72+
73+
### Performance
74+
75+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
76+
|--------|-------------------------|---------------|-------------------|
77+
| Latency | Direct proxy routing = minimal overhead (~1-2ms) | Additional hop through gateway logic (~5-10ms minimum) | Reverse Proxy |
78+
| Throughput | Each connection directly streams to target server | Gateway becomes bottleneck for all tool calls | Reverse Proxy |
79+
| Network Efficiency | Client maintains persistent connections to specific servers | Gateway must proxy all request/response payloads | Reverse Proxy |
80+
| CPU Usage | [Nginx](https://Nginx.org/) handles routing, minimal Python involvement | Gateway must parse, route, and proxy every MCP message | Reverse Proxy |
81+
| Memory | Low gateway memory usage, servers handle their own state | Gateway must buffer requests/responses, maintain backend connections | Reverse Proxy |
82+
| **Protocol Independence** | **Nginx passes through any protocol - not MCP-specific** | **Gateway must understand MCP protocol specifics** | **Reverse Proxy** |
83+
| Implementation Language | Python suitable due to Nginx handling message routing | **Requires Go/Rust for enterprise performance requirements** | Reverse Proxy |
84+
| **Implementation Complexity** | **Nginx handles protocol details, minimal state management needed** | **Requires elaborate state management, protocol awareness, connection lifecycle management** | **Reverse Proxy** |
85+
86+
### Security
87+
88+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
89+
|--------|-------------------------|---------------|-------------------|
90+
| Authentication | Nginx auth_request pattern = proven, battle-tested | Gateway must implement auth validation | Equivalent |
91+
| Authorization | Fine-grained scope validation per server/tool before routing | Can implement same fine-grained scopes | Equivalent |
92+
| Audit Trail | Complete Nginx access logs + auth server logs + IdP logs | Gateway logs all tool calls | Equivalent |
93+
| Attack Surface | Direct server access blocked, only authenticated routes exposed | Single endpoint, easier to monitor but single point of failure | Equivalent |
94+
| Token Validation | Centralized in auth server, cached for performance | Must implement JWT/session validation | Equivalent |
95+
96+
### Maintainability
97+
98+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
99+
|--------|-------------------------|---------------|-------------------|
100+
| Service Registration & Configuration | Dynamic Nginx config generation and reload for new servers | Dynamic tool registration without infrastructure changes | Tools Gateway |
101+
| Debugging | Multi-component debugging (Nginx + auth server + target server) | Centralized logging and error handling | Tools Gateway |
102+
| Transport Support | Must handle SSE/HTTP variations per server | Must implement transport variations in gateway code | Equivalent |
103+
| Error Handling | Error propagation through multiple layers | Must implement error translation from backends | Equivalent |
104+
105+
### Scaling
106+
107+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
108+
|--------|-------------------------|---------------|-------------------|
109+
| Horizontal Scaling | Can load balance multiple gateway instances easily | Gateway must maintain backend connection pools | Reverse Proxy |
110+
| **Backend Scaling** | **Each MCP server scales independently** | **Gateway must implement backend load balancing** | **Reverse Proxy** |
111+
| **Resource Isolation** | **Both handle backend failures via health checks, but Nginx transparently proxies data plane traffic end-to-end** | **Gateway must maintain both data plane MCP connections AND separate health checks to backends** | **Reverse Proxy** |
112+
| Connection Pooling | Direct client connections to needed servers only | Gateway must manage M×N connection pools | Reverse Proxy |
113+
| Geographic Distribution | Can proxy to servers in different regions | Complex backend routing required | Reverse Proxy |
114+
| **Protocol Extensibility** | **Same architecture works for Agent-to-Agent (A2A) or other protocols** | **MCP-specific implementation limits future protocol support** | **Reverse Proxy** |
115+
116+
### Operational Complexity
117+
118+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
119+
|--------|-------------------------|---------------|-------------------|
120+
| Monitoring | Must monitor Nginx + auth server + N backend servers | Monitor gateway + auth server + N backend servers (simpler) | Tools Gateway |
121+
| Service Discovery | Complex Nginx config regeneration | Dynamic tool registration | Tools Gateway |
122+
| Health Checking | Health status triggers Nginx config regeneration and reload | Gateway makes runtime routing decisions based on health | Equivalent |
123+
| Certificate Management | Single domain cert for gateway endpoint | Only gateway needs external certs | Equivalent |
124+
| Log Aggregation | Focused logs per component (Nginx, auth, individual MCP servers) | All tool calls centralized in gateway logs | Equivalent |
125+
126+
### Enterprise Integration & User Experience
127+
128+
| Aspect | Reverse Proxy (Current) | Tools Gateway | Preferable Approach |
129+
|--------|-------------------------|---------------|-------------------|
130+
| **Client Configuration & Mental Model** | **Must configure N server endpoints, understand Nginx routing + auth + backend servers** | **Single endpoint configuration, simple "one gateway, many tools" concept** | **Tools Gateway** |
131+
| Network Policies | Must allowlist N different paths | Single path to allowlist | Tools Gateway |
132+
| Change Management | Adding new server requires client reconfiguration | New tools appear automatically via discovery | Tools Gateway |
133+
| Vendor Integration | Each vendor needs separate endpoint configuration | Vendors configure single endpoint | Tools Gateway |
134+
| Tool Discovery | Discovery via Registry UI or MCPGW MCP server | Automatic through tools/list call | Equivalent |
135+
| Error Messages | May be confusing due to multiple layers | Clearer, centralized error formatting | Tools Gateway |
136+
| Testing | Must test each server endpoint individually | Single endpoint for all testing | Tools Gateway |
137+
138+
## Implementation Considerations
139+
140+
### Protocol Independence Benefits
141+
The reverse proxy architecture provides protocol independence:
142+
- **Future Protocols**: Can support Agent-to-Agent (A2A), custom protocols without gateway changes
143+
- **Protocol Evolution**: MCP protocol changes don't require gateway modifications
144+
- **Mixed Environments**: Can proxy HTTP, WebSocket, gRPC, or custom protocols simultaneously
145+
146+
### Tools Gateway Implementation Challenges
147+
A tools gateway requires:
148+
- **Language Choice**: Python insufficient for performance; requires Go/Rust implementation
149+
- **MCP Client Library**: Must embed full MCP client for backend communication and keep client updated with evolving MCP specification changes
150+
- **Protocol Parsing**: Must understand and parse all MCP message types
151+
- **Connection Handling**: Complex connection lifecycle management
152+
- **Error Translation**: Convert backend MCP errors to client-readable format
153+
154+
155+
156+
## Conclusion
157+
158+
Both architectures have merits:
159+
160+
- **Reverse Proxy**: Better performance, proven scalability, protocol independence, battle-tested Nginx foundation, allows Python implementation due to Nginx handling message routing
161+
- **Tools Gateway**: Better developer experience, easier enterprise adoption, simpler operations, requires Go/Rust implementation for enterprise performance requirements
162+
163+
The choice depends on organizational priorities:
164+
165+
- **Performance-first organizations** (high-frequency trading, real-time systems): Stay with reverse proxy
166+
- **Protocol-diverse environments** (supporting A2A, custom protocols): Reverse proxy provides flexibility
167+
- **Python-preferred development teams**: Reverse proxy allows continued Python development while Nginx handles performance-critical routing
168+
- **Developer experience-first organizations** (internal tooling, enterprise IT): Consider tools gateway but must invest in Go/Rust development expertise
169+
- **Hybrid organizations**: Implement both patterns and let teams choose
170+
171+
The current implementation is production-ready and protocol-independent. The reverse proxy approach provides more architectural flexibility for future protocol support while allowing the team to continue developing in Python.

0 commit comments

Comments
 (0)