# membrane/api-gateway architecture

> Architecture diagram of the GitHub repository membrane/api-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/membrane/api-gateway
- Repository: https://github.com/membrane/api-gateway

## Overview

Membrane is an API gateway: a client request enters the gateway, configuration determines its processing, and routing forwards it to a backend. The README also documents OpenAPI deployment and validation, SOAP/WSDL integration, security, transformation, orchestration, traffic control, AI/MCP, and observability. The excerpts show router initialization, exchange representation, servlet request/response handling, and OAuth2 and ACME integrations; many feature links below are documented capabilities rather than inspected call paths.

Main entry points: [`core/src/main/java/com/predic8/membrane/core/proxies/Proxy.java`](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/proxies/Proxy.java) (Proxy and routing), [`core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java`](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java) (Gateway router), [`war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java`](https://github.com/membrane/api-gateway/blob/master/war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java) (Servlet ingress), [`core/src/main/java/com/predic8/membrane/core/transport/http/HttpClient.java`](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/transport/http/HttpClient.java) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Gateway runtime"]
  node_servlet["Servlet ingress"]
  node_exchange["HTTP exchange<br/>[Exchange.java]"]
  node_router["Gateway router<br/>[DefaultRouter.java]"]
  node_proxy["Proxy and routing<br/>[Proxy.java]"]
  node_httpclient["HTTP client<br/>[HttpClient.java]"]
end

subgraph group_config["Configuration"]
  node_yaml["YAML configuration<br/>[YamlLoader.java]"]
  node_configgrammar["Config annotations<br/>[MCElement.java]"]
end

subgraph group_features["API capabilities"]
  node_openapi["OpenAPI support"]
  node_soap["SOAP and WSDL<br/>[Service.java]"]
  node_transform["Message transforms"]
  node_graphql["GraphQL protection"]
  node_mcp["AI and MCP"]
end

subgraph group_security["Security"]
  node_oauth["OAuth2 authorization"]
  node_tls["TLS certificates<br/>[Acme.java]"]
end

subgraph group_ops["Traffic and operations"]
  node_traffic["Traffic control"]
  node_observability[("Traffic storage<br/>[ExchangeStore.java]")]
end

node_client(("API client"))
node_backend(("API backend"))

node_client -.->|"sends request"| node_servlet
node_servlet -->|"creates exchange"| node_exchange
node_servlet -.->|"dispatches request"| node_router
node_router -.->|"routes traffic"| node_proxy
node_proxy -.->|"forwards request"| node_httpclient
node_httpclient -.->|"sends request"| node_backend
node_backend -.->|"returns response"| node_client
node_yaml -.->|"configures gateway"| node_router
node_configgrammar -->|"describes settings"| node_yaml
node_router -.->|"deploys and validates"| node_openapi
node_proxy -.->|"integrates services"| node_soap
node_proxy -.->|"transforms messages"| node_transform
node_proxy -.->|"protects requests"| node_graphql
node_proxy -.->|"secures APIs"| node_oauth
node_router -.->|"secures transport"| node_tls
node_router -.->|"provides AI gateway"| node_mcp
node_proxy -.->|"controls traffic"| node_traffic
node_router -.->|"observes exchanges"| node_observability

click node_servlet "https://github.com/membrane/api-gateway/blob/master/war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java"
click node_exchange "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/exchange/Exchange.java"
click node_router "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java"
click node_proxy "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/proxies/Proxy.java"
click node_httpclient "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/transport/http/HttpClient.java"
click node_yaml "https://github.com/membrane/api-gateway/blob/master/annot/src/main/java/com/predic8/membrane/annot/yaml/YamlLoader.java"
click node_configgrammar "https://github.com/membrane/api-gateway/blob/master/annot/src/main/java/com/predic8/membrane/annot/MCElement.java"
click node_openapi "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/openapi/validators/QueryParameterValidator.java"
click node_soap "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/util/wsdl/parser/Service.java"
click node_transform "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/lang/groovy/adapted/StreamingTemplateEngine.java"
click node_graphql "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/graphql/GraphQLProtectionInterceptor.java"
click node_oauth "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/authorizationservice/AuthorizationService.java"
click node_tls "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/config/security/acme/Acme.java"
click node_mcp "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/mcp/McpSessionManager.java"
click node_traffic "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/FlowController.java"
click node_observability "https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/exchangestore/ExchangeStore.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_servlet,node_exchange,node_router,node_proxy,node_httpclient,node_client toneBlue
class node_yaml,node_configgrammar toneAmber
class node_openapi,node_soap,node_transform,node_graphql,node_mcp,node_backend toneMint
class node_oauth,node_tls toneRose
class node_traffic,node_observability toneIndigo
```

## Components

### Gateway runtime

- [Servlet ingress](https://github.com/membrane/api-gateway/blob/master/war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java): `war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java`
- [HTTP exchange](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/exchange/Exchange.java): `core/src/main/java/com/predic8/membrane/core/exchange/Exchange.java`
- [Gateway router](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java): `core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java`
- [Proxy and routing](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/proxies/Proxy.java): `core/src/main/java/com/predic8/membrane/core/proxies/Proxy.java`
- [HTTP client](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/transport/http/HttpClient.java): `core/src/main/java/com/predic8/membrane/core/transport/http/HttpClient.java`

### Configuration

- [YAML configuration](https://github.com/membrane/api-gateway/blob/master/annot/src/main/java/com/predic8/membrane/annot/yaml/YamlLoader.java): `annot/src/main/java/com/predic8/membrane/annot/yaml/YamlLoader.java`
- [Config annotations](https://github.com/membrane/api-gateway/blob/master/annot/src/main/java/com/predic8/membrane/annot/MCElement.java): `annot/src/main/java/com/predic8/membrane/annot/MCElement.java`

### API capabilities

- [OpenAPI support](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/openapi/validators/QueryParameterValidator.java): `core/src/main/java/com/predic8/membrane/core/openapi/validators/QueryParameterValidator.java`
- [SOAP and WSDL](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/util/wsdl/parser/Service.java): `core/src/main/java/com/predic8/membrane/core/util/wsdl/parser/Service.java`
- [Message transforms](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/lang/groovy/adapted/StreamingTemplateEngine.java): `core/src/main/java/com/predic8/membrane/core/lang/groovy/adapted/StreamingTemplateEngine.java`
- [GraphQL protection](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/graphql/GraphQLProtectionInterceptor.java): `core/src/main/java/com/predic8/membrane/core/graphql/GraphQLProtectionInterceptor.java`
- [AI and MCP](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/mcp/McpSessionManager.java): `core/src/main/java/com/predic8/membrane/core/interceptor/mcp/McpSessionManager.java`

### Security

- [OAuth2 authorization](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/authorizationservice/AuthorizationService.java): `core/src/main/java/com/predic8/membrane/core/interceptor/oauth2/authorizationservice/AuthorizationService.java`
- [TLS certificates](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/config/security/acme/Acme.java): `core/src/main/java/com/predic8/membrane/core/config/security/acme/Acme.java`

### Traffic and operations

- [Traffic control](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/interceptor/FlowController.java): `core/src/main/java/com/predic8/membrane/core/interceptor/FlowController.java`
- [Traffic storage](https://github.com/membrane/api-gateway/blob/master/core/src/main/java/com/predic8/membrane/core/exchangestore/ExchangeStore.java): `core/src/main/java/com/predic8/membrane/core/exchangestore/ExchangeStore.java`

### Other components

- **API client**
- **API backend**

## Connections

- API client → Servlet ingress: sends request
- Servlet ingress → HTTP exchange: creates exchange (evidence: `war/src/main/java/com/predic8/membrane/servlet/embedded/HttpServletHandler.java`)
- Servlet ingress → Gateway router: dispatches request
- Gateway router → Proxy and routing: routes traffic (evidence: `core/src/main/java/com/predic8/membrane/core/router/DefaultRouter.java`)
- Proxy and routing → HTTP client: forwards request
- HTTP client → API backend: sends request
- API backend → API client: returns response
- YAML configuration → Gateway router: configures gateway (evidence: `README.md`)
- Config annotations → YAML configuration: describes settings (evidence: `annot/src/main/java/com/predic8/membrane/annot/MCElement.java`)
- Gateway router → OpenAPI support: deploys and validates (evidence: `README.md`)
- Proxy and routing → SOAP and WSDL: integrates services (evidence: `README.md`)
- Proxy and routing → Message transforms: transforms messages (evidence: `README.md`)
- Proxy and routing → GraphQL protection: protects requests (evidence: `README.md`)
- Proxy and routing → OAuth2 authorization: secures APIs (evidence: `README.md`)
- Gateway router → TLS certificates: secures transport (evidence: `README.md`)
- Gateway router → AI and MCP: provides AI gateway (evidence: `README.md`)
- Proxy and routing → Traffic control: controls traffic (evidence: `README.md`)
- Gateway router → Traffic storage: observes exchanges (evidence: `README.md`)
