Gateway & Nginx Routing
Relevant source files
The following files were used as context for generating this wiki page:
The Gateway & Nginx Routing system provides a centralized reverse proxy and entry point for the SecondLayer platform. It handles SSL termination, traffic load balancing between frontend and backend services, and specialized routing for Model Context Protocol (MCP) endpoints, OAuth 2.0 flows, and file uploads. In environments like Staging, the gateway ensures that distinct services (PostgreSQL, Redis, Backend API) are isolated within Docker networks while remaining accessible through standard HTTPS ports.
Sources: deployment/INDEX.md:54-68, deployment/GATEWAY_SETUP.md:7-13, deployment/nginx/README.md:3-10
Architecture Overview
The SecondLayer architecture utilizes Nginx as a reverse proxy to route external traffic to internal services running in Docker containers. The routing logic is categorized into functional modules: OAuth discovery, MCP protocol endpoints (SSE), REST API webhooks, and Frontend Single Page Application (SPA) routes.
The diagram above illustrates how the Nginx Gateway serves as the single point of entry, distributing traffic based on URL patterns to the appropriate backend or frontend service.
Sources: deployment/nginx/README.md:12-18, deployment/nginx-stage.legal.org.ua.conf:15-25, deployment/GATEWAY_SETUP.md:15-22
Endpoint Modules
OAuth 2.0 and Discovery
The gateway manages OAuth 2.0 authorization flows required for integrations with platforms like Claude.ai and ChatGPT. It provides metadata discovery via standard RFC 8414 paths.
| Endpoint | Purpose | Description |
|---|---|---|
/.well-known/oauth-authorization-server | OAuth Discovery | RFC 8414 Metadata for clients |
/.well-known/openid-configuration | OIDC Discovery | OpenID Connect compatibility |
/oauth/authorize | Authorization | User authorization page |
/oauth/token | Token Exchange | Token issuance and exchange |
/authorize | Compatibility | Redirects to /oauth/authorize for Claude.ai |
Sources: deployment/nginx/README.md:112-124, deployment/nginx-stage.legal.org.ua.conf:75-125
MCP and SSE Streaming
Model Context Protocol (MCP) support is implemented using Server-Sent Events (SSE). The gateway is configured to handle long-lived connections by disabling proxy buffering and extending read timeouts.
Nginx is specifically configured with proxy_buffering off and chunked_transfer_encoding on to support the real-time nature of MCP tool execution and streaming advice.
Sources: deployment/nginx-stage.legal.org.ua.conf:153-210, mcp_backend/REMOTE_MCP_DEPLOYMENT.md:195-212
API and Upload Management
The /api route handles standard REST operations, while /api/upload is specifically tuned for chunked file uploads with dedicated rate limiting and buffer sizes.
- Rate Limiting: A
limit_req_zonenamedupload_limitis defined with a rate of 100 requests/second per IP and a burst capacity of 50. - Buffer Settings:
client_body_buffer_sizeis set to 10M for uploads to handle larger segments in memory. - Timeouts:
proxy_read_timeoutis extended to 120s for upload operations.
Sources: deployment/nginx-stage.legal.org.ua.conf:8-10, deployment/nginx-stage.legal.org.ua.conf:225-255
Environment-Specific Configuration
The gateway uses different port mappings and upstream configurations depending on the environment (Staging vs. Local). While Local development often bypasses the gateway for direct service access, the Staging environment on mail.lexapp.co.ua relies on it for SSL termination and unified access.
| Feature | Staging | Local |
|---|---|---|
| Domain | stage.legal.org.ua | localdev.legal.org.ua |
| Backend Port | 3004 | 3000 |
| Frontend Port | 8092 | 5173 |
| Nginx Active | Yes | Optional/Direct Access |
| SSL Termination | Certbot/LetsEncrypt | None/Self-signed |
Sources: deployment/GATEWAY_SETUP.md:15-22, deployment/INDEX.md:88-91, deployment/nginx/README.md:180-195
Management and Operations
The platform provides a manage-gateway.sh script to orchestrate the gateway and associated services.
Core Commands
./manage-gateway.sh gateway start # Starts the legal-nginx-gateway container
./manage-gateway.sh gateway test # Executes 'nginx -t' to verify configuration
./manage-gateway.sh gateway restart # Restarts the gateway to apply changes
./manage-gateway.sh logs gateway # Tail gateway access and error logs
Sources: deployment/INDEX.md:112-115, deployment/GATEWAY_SETUP.md:65-72
Security Headers
The gateway enforces several security headers globally for all HTTPS traffic:
Strict-Transport-Security: Enforces HTTPS for one year.X-Frame-Options: Set toSAMEORIGINto prevent clickjacking.X-Content-Type-Options: Set tonosniff.Referrer-Policy: Set tostrict-origin-when-cross-origin.
Sources: deployment/nginx-stage.legal.org.ua.conf:56-61
Summary
The Gateway & Nginx Routing system is a critical infrastructure component that abstracts the underlying Docker-based microservices into a unified web interface. By utilizing modular include files (api-endpoints.conf, mcp-endpoints.conf, etc.) and specialized proxy configurations for SSE and high-volume uploads, the gateway provides a secure, scalable, and compliant entry point for both human users and AI-driven MCP clients.