# softwareag/webmethods-api-gateway architecture

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

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

## Overview

##### Project Type and Purpose
- This repo is not a single microservice or UI project, but a comprehensive “resource and sample” repository for the webMethods API Gateway product.
- It contains:
- API definitions and Swagger JSON for each gateway service (apigatewayservices/)
- Postman collections for testing those APIs
- Architecture and operations documentation (docs/)
- Getting-started examples (gettingstarted/)
- Deployment samples for Docker, Kubernetes, Helm, OpenShift, and Command Central (samples/)
- Purpose: illustrate how to deploy, configure, extend, and interact with the API Gateway runtime and its supporting components.

##### File Structure Analysis
- Top-level directories:
- apigatewayservices – full list of gateway service Swagger definitions + Postman collections
- docs – deep dives into architecture (e.g. Elasticsearch/Kibana setup, security), operations, policies, diagnostics, features
- gettingstarted – minimal GraphQL and Kubernetes examples for a quick launch
- samples – end-to-end deployment templates for Docker, Kubernetes (plain manifests, Helm charts), OpenShift, Command Central
- attachments – static images and zip archives used by the README
- Patterns:
- Control plane vs data plane separation (management APIs, UI docs vs runtime service definitions)
- Infrastructure-as-code (Helm, YAML manifests)
- Observability integration (Elasticsearch + Kibana)

##### Key Insights from README
- API Gateway provides:
- A web UI for admin and API design
- A runtime cluster that applies policies and routes incoming API traffic
- Analytics dashboard backed by Elasticsearch/Kibana
- DevOps options: Cloud, Docker image, CLI/Command-Central, Helm charts
- Users import APIs via archives, assign policies, create applications (API keys), and monitor analytics.

##### Main Components
A. Control Plane
1) Admin UI (web application served by gateway runtime)
2) Management REST APIs (Swagger definitions under apigatewayservices/)
3) DevOps Integration: Command Central / CLI / Helm charts / Docker Compose
B. Data Plane
1) API Gateway Runtime Cluster (Nginx ingress or built-in HTTP listener)
2) Policy Enforcement Engine (global policies, security, transformation)
3) Routing to Backend Services (customer-owned microservices, SOAP/REST endpoints)
C. Data Stores & Caches
1) Configuration & state DB (internal data store)
2) Analytics Store: Elasticsearch cluster
3) Caching Tier: Terracotta cluster (session and policy cache)
D. Observability
1) Kibana UI
2) Metrics & transaction logs (shipped from gateway via Elasticsearch plugins)
E. External Systems
1) API Portal (for developer onboarding)
2) Backend services and external APIs
3) Identity provider (OAuth/OpenID Connect)

##### Interactions and Data Flows
- Management flow (Control Plane):
1) Administrator uses Admin UI → Management REST API → Config DB
2) DevOps pipelines use Helm/Docker CLI → push configuration via Management API
- Runtime flow (Data Plane):
1) Client request → Ingress/Nginx → Gateway runtime nodes
2) Policy Engine consults cache (Terracotta) and DB → enforces rate-limit, security, transformations
3) Gateway forwards request → target backend service → receives response
4) Transaction logs & metrics → Elasticsearch → Kibana

##### Architectural Patterns & Principles
- Control-Plane / Data-Plane separation to decouple management from runtime
- Externalize state in highly available stores (SQL/NoSQL for config, Elasticsearch for analytics, Terracotta for cache)
- Containerized deployments with declarative manifests (Docker Compose, Kubernetes, Helm)
- Extensibility points: new policies (JSON files under apigatewayservices), custom destinations, custom scripts
- Secure-by-design: integrate with external identity provider, TLS termination at ingress

##### Final Checklist
[ ] Components grouped by Control Plane, Data Plane, Data Stores, External Systems
[ ] Labels for technologies: Elasticsearch, Kibana, Terracotta, Nginx, Helm, Docker, Kubernetes
[ ] Notes on protocol (HTTPS, REST) and authentication (APIKey, OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        AdminUI["Admin UI (Web UI)"]:::control
        MgmtAPI["Management REST APIs"]:::control
        subgraph "DevOps Integration"
            direction TB
            CLI["CLI / Command Central"]:::control
            HelmCP["Helm Charts"]:::control
            DockerCP["Docker Compose Scripts"]:::control
        end
    end

    %% Data Plane
    subgraph "Data Plane"
        direction TB
        Ingress["Ingress / Nginx"]:::runtime
        Gateway["Gateway Runtime Cluster"]:::runtime
        PolicyEngine["Policy Enforcement Engine"]:::runtime
        Routing["Routing to Backend Services"]:::runtime
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        ConfigDB["Config & State DB"]:::store
        Elasticsearch["Elasticsearch Cluster"]:::store
        Terracotta["Terracotta Cache Cluster"]:::store
    end

    %% Observability
    subgraph "Observability"
        direction TB
        Kibana["Kibana UI"]:::obs
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        APIPortal["API Portal"]:::external
        Backend["Backend Services / External APIs"]:::external
        Identity["Identity Provider (OAuth/OIDC)"]:::external
    end

    %% Developer Artifacts
    subgraph "Developer Artifacts & Samples"
        direction TB
        APISvc["apigatewayservices/ (Swagger JSON)"]:::artifact
        Postman["Postman Collections"]:::artifact
        Docs["Documentation (docs/)"]:::artifact
        GettingStarted["Getting-Started Examples"]:::artifact
        Attach["Attachments"]:::artifact
        ExtConfig["External Configurations"]:::artifact
        OpenShift["OpenShift Templates"]:::artifact
    end

    %% Flows
    AdminUI -->|"HTTPS REST"| MgmtAPI
    CLI -->|"push config"| MgmtAPI
    HelmCP -->|"push config"| MgmtAPI
    DockerCP -->|"push config"| MgmtAPI
    MgmtAPI -->|writes| ConfigDB

    APIPortal -->|"Admin onboards APIs"| AdminUI

    ClientRequest(("Client Request")):::external -->|HTTPS| Ingress
    Ingress -->|forwards| Gateway
    Gateway -->|enforce policies| PolicyEngine
    PolicyEngine -->|calls cache| Terracotta
    PolicyEngine -->|calls DB| ConfigDB
    PolicyEngine -->|auth via| Identity
    PolicyEngine -->|routes| Routing
    Routing -->|invoke| Backend
    Gateway -->|logs & metrics| Elasticsearch
    Elasticsearch -->|visualize| Kibana

    %% Developer artifacts links
    APISvc --> MgmtAPI
    Postman --> MgmtAPI
    Docs --> AdminUI
    GettingStarted --> Ingress
    Attach --> Docs
    ExtConfig --> CLI
    OpenShift --> CLI

    %% Click Events
    click MgmtAPI "https://github.com/softwareag/webmethods-api-gateway/tree/master/apigatewayservices/"
    click APISvc "https://github.com/softwareag/webmethods-api-gateway/tree/master/apigatewayservices/"
    click Postman "https://github.com/softwareag/webmethods-api-gateway/tree/master/apigatewayservices/postmancollections/"
    click CLI "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/commandcentral/templates/"
    click HelmCP "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/helm/cluster-deployment/apigateway/"
    click DockerCP "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/docker/deploymentscripts/"
    click Docs "https://github.com/softwareag/webmethods-api-gateway/tree/master/docs/"
    click GettingStarted "https://github.com/softwareag/webmethods-api-gateway/tree/master/gettingstarted/"
    click Ingress "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/deploymentscripts/"
    click HelmCP "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/helm/cluster-deployment/apigateway/templates/"
    click PolicyEngine "https://github.com/softwareag/webmethods-api-gateway/tree/master/apigatewayservices/"
    click Elasticsearch "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/docker/deploymentscripts/apigw-elasticsearch-cluster-kibana/"
    click Elasticsearch "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/docker/deploymentscripts/apigw-elasticsearch-cluster/"
    click Elasticsearch "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/deploymentscripts/apigw-embedded-elasticsearch/"
    click Elasticsearch "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/deploymentscripts/apigw-sidecar-elasticsearch/"
    click Terracotta "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/kubernetes/helm/cluster-deployment/apigateway/charts/terracotta/"
    click Kibana "https://github.com/softwareag/webmethods-api-gateway/blob/master/samples/docker/deploymentscripts/apigw-elasticsearch-cluster-kibana/kibana.yml"
    click ExtConfig "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/externalconfigurations/"
    click OpenShift "https://github.com/softwareag/webmethods-api-gateway/tree/master/samples/openshift/templatescripts/"
    click Attach "https://github.com/softwareag/webmethods-api-gateway/tree/master/attachments/"
    click Docs "https://github.com/softwareag/webmethods-api-gateway/tree/master/docs/articles/architecture/Securing-Elasticsearch-for-API-Gateway-10.11/attachments/"

    %% Styles
    classDef control fill:#AED6F1,stroke:#2980B9,color:#1B4F72
    classDef runtime fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef store fill:#F9E79F,stroke:#D4AC0D,color:#7D6608
    classDef obs fill:#D7BDE2,stroke:#8E44AD,color:#4A235A
    classDef external fill:#D5D8DC,stroke:#7B7D7D,color:#2C3E50
    classDef artifact fill:#F5CBA7,stroke:#CA6F1E,color:#78281F
    class APISvc,Postman,Docs,GettingStarted,Attach,ExtConfig,OpenShift artifact
    class AdminUI,MgmtAPI,CLI,HelmCP,DockerCP control
    class Ingress,Gateway,PolicyEngine,Routing runtime
    class ConfigDB,Elasticsearch,Terracotta store
    class Kibana obs
    class APIPortal,Backend,Identity,ClientRequest external
```
