All documentation is organized by conceptual domain. Each entry links to the authoritative document for that concept.
Machine-readable taxonomy:
SimpleL7Proxy/taxonomy/concepts.jsoncontains the full concept graph with IDs, relationships, settings cross-references, and response code mappings used to generate and validate documentation.
The end-to-end path a request travels from client to backend and back.
| Concept | Document |
|---|---|
| Ingress, listener port, worker count | ENVIRONMENT_VARIABLES.md |
| Priority queue, priority levels, default priority | ADVANCED_CONFIGURATION.md |
| TTL (Time-to-Live) and per-request overrides | TIMEOUTS.md |
| Worker dispatch, concurrent thread count | ENVIRONMENT_VARIABLES.md |
| Response headers injected by the proxy | RESPONSE_CODES.md |
| All proxy-originated and pass-through response codes | RESPONSE_CODES.md |
| Request and response header reference (S7P* headers) | RESPONSE_CODES.md |
How the proxy discovers, probes, and selects backend hosts.
| Concept | Document |
|---|---|
| Backend host configuration (Host1–Host9) | BACKEND_HOSTS.md |
| Connection string format (all keys) | BACKEND_HOSTS.md |
| Legacy per-variable format (deprecated) | BACKEND_HOSTS.md |
| Path-based routing, catch-all hosts, strip prefix | BACKEND_HOSTS.md |
| Direct mode (serverless / no probing) | BACKEND_HOSTS.md |
Stream processor (processor=OpenAI) |
AI_FOUNDRY_INTEGRATION.md |
| IP override, DNS bypass | BACKEND_HOSTS.md |
| Health polling, success rate, active pool | BACKEND_HOSTS.md |
| Load balance modes (roundrobin / latency / random) | LOAD_BALANCING.md |
| Backend selection pipeline (path → order → circuit gate) | LOAD_BALANCING.md |
| Shared iterators | LOAD_BALANCING.md |
| Iteration mode, max attempts | LOAD_BALANCING.md |
Mechanisms that prevent failures from propagating to clients.
| Concept | Document |
|---|---|
| Circuit breaker: CLOSED / OPEN states | CIRCUIT_BREAKER.md |
| Sliding window, auto-recovery | CIRCUIT_BREAKER.md |
| Progressive delay (50%–90% threshold) | CIRCUIT_BREAKER.md |
| Global blocked check (all circuits OPEN → 503) | CIRCUIT_BREAKER.md |
| Acceptable status codes | CIRCUIT_BREAKER.md |
| Retry across backends | LOAD_BALANCING.md |
| Requeue on 429 + S7PREQUEUE | LOAD_BALANCING.md |
| TTL (total request budget) | TIMEOUTS.md |
| Per-host Timeout | TIMEOUTS.md |
| Per-request override headers (S7PTTL, S7PTimeout) | TIMEOUTS.md |
| AsyncTriggerTimeout / AsyncTimeout / AsyncTTLSecs | TIMEOUTS.md |
Validation and priority rules applied before a request enters the queue.
| Concept | Document |
|---|---|
| Validation pipeline execution order | REQUEST_VALIDATION.md |
| App ID validation (Entra allowlist, step 1) | REQUEST_VALIDATION.md |
| Header stripping (DisallowedHeaders, step 2) | REQUEST_VALIDATION.md |
| Required headers (step 4, returns 417) | REQUEST_VALIDATION.md |
| Header value validation rules (step 5) | REQUEST_VALIDATION.md |
| User profiles: structure, fields, refresh | USER_PROFILES.md |
| User ID field, profile lookup | USER_PROFILES.md |
| Suspended users | USER_PROFILES.md |
| async-config profile field | USER_PROFILES.md |
| Priority mapping (PriorityKeys / PriorityValues / PriorityWorkers) | ADVANCED_CONFIGURATION.md |
| Per-user throttling (UserPriorityThreshold) | ADVANCED_CONFIGURATION.md |
Long-running request handling that decouples client wait from backend processing.
| Concept | Document |
|---|---|
| Async mode overview, three-level enablement | AsyncOperation.md |
| AsyncTriggerTimeout and async upgrade (202 response) | TIMEOUTS.md |
| Azure Service Bus configuration and status events | AsyncOperation.md |
| Result blob storage, SAS token lifetime | AsyncOperation.md |
| Blob retention and lifecycle management | StorageBlobConfig.md |
| Async processing variables (full reference) | ENVIRONMENT_VARIABLES.md |
How the proxy exposes telemetry about its own operation.
| Concept | Document |
|---|---|
| ProxyEvent model, event headers, fan-out architecture | OBSERVABILITY.md |
| Application Insights (primary production sink) | OBSERVABILITY.md |
| Event Hubs (high-volume streaming) | OBSERVABILITY.md |
| Local log file (development) | OBSERVABILITY.md |
Token telemetry from SSE streams (processor=OpenAI) |
OBSERVABILITY.md |
| Custom event logger (IEventClient + IHostedService) | OBSERVABILITY.md |
| Health endpoints: /liveness, /readiness, /startup | HEALTH_CHECKING.md |
| Sidecar mode health isolation (port 9000) | HEALTH_CHECKING.md |
| Observability logging variables | ENVIRONMENT_VARIABLES.md |
How settings reach the proxy and when they take effect.
| Concept | Document |
|---|---|
| Warm / Cold / Hidden setting classification | CONFIGURATION_SETTINGS.md |
| Settings organized by frequency of use (Essential / Common / Advanced) | CONFIGURATION_CATEGORIES.md |
| Azure App Configuration: setup, RBAC, Sentinel pattern | AZURE_APP_CONFIGURATION.md |
| Composite connection string format | BACKEND_HOSTS.md |
| All environment variables (exhaustive reference) | ENVIRONMENT_VARIABLES.md |
| Minimum required configuration | ENVIRONMENT_VARIABLES.md |
| Copy-paste configurations for common scenarios | SCENARIOS.md |
How the proxy authenticates to backends and restricts inbound callers.
| Concept | Document |
|---|---|
Managed Identity for backends (usemi=true) |
BACKEND_HOSTS.md |
| Keyless auth for Azure OpenAI / AI Foundry | AI_FOUNDRY_INTEGRATION.md |
| OAuth2 Bearer token attachment | BACKEND_HOSTS.md |
| App ID allowlist (Entra, >13 app IDs) | REQUEST_VALIDATION.md |
| Header stripping to prevent internal header leakage | REQUEST_VALIDATION.md |
| VNet deployment and sovereign cloud | OVERVIEW.md |
| Security overview and responsible disclosure | SECURITY.md |
| Securing the proxy with APIM | POC-Secure-the-proxy.md |
How the proxy is packaged and run on Azure.
| Concept | Document |
|---|---|
| Azure Container Apps deployment | CONTAINER_DEPLOYMENT.md |
| Sidecar deployment (proxy + health probe containers) | SIDECAR_DEPLOYMENT.md |
| Build and deploy scripts, parameters file | SIDECAR_DEPLOYMENT.md |
| Azure AI Foundry / OpenAI integration patterns | AI_FOUNDRY_INTEGRATION.md |
| APIM integration and reference policy | ../APIM-Policy/readme.md |
| Day-2 operations | ../deployment/DAY2_OPERATIONS.md |
Named HTTP signals that cross the client-proxy and proxy-backend boundaries.
| Header | Direction | Document |
|---|---|---|
S7PPriorityKey |
Client → proxy | RESPONSE_CODES.md |
S7PTTL |
Client → proxy | TIMEOUTS.md |
S7PTimeout |
Client → proxy | TIMEOUTS.md |
S7PAsyncMode |
Client → proxy | AsyncOperation.md |
S7PDEBUG |
Client → proxy | RESPONSE_CODES.md |
S7PREQUEUE |
Backend → proxy | RESPONSE_CODES.md |
x-Request-Queue-Duration |
Proxy → client | RESPONSE_CODES.md |
x-Request-Process-Duration |
Proxy → client | RESPONSE_CODES.md |
x-Request-Worker |
Proxy → client | RESPONSE_CODES.md |
BackendHost |
Proxy → client | RESPONSE_CODES.md |
Total-Latency |
Proxy → client | RESPONSE_CODES.md |
| Goal | Start here |
|---|---|
| First deployment | QUICKSTART.md |
| Local development | BEGINNER_DEVELOPMENT.md |
| Advanced development & performance tuning | ADVANCED_DEVELOPMENT.md |
| Understanding the architecture | OVERVIEW.md |
| Diagnosing a problem | TroubleshootTOC.md |
| Code structure and internals | design.md |
| Scenario | Document |
|---|---|
| OpenAI failover across regions | POC-OpenAI-Failover.md |
| Failover configuration | POC-Failover-configuration.md |
| Priority-based routing | POC-Priority-configuration.md |
| Securing the proxy | POC-Secure-the-proxy.md |
| Securing APIM | POC-security-the-apim.md |
| Chargeback and token tracking | POC-Chargeback.md |