# kong/kong-js-pdk architecture

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

- Interactive diagram: https://gitdiagram.com/kong/kong-js-pdk
- Repository: https://github.com/kong/kong-js-pdk

## Overview

##### Project type and purpose
- This is an open-source tool (kong-js-pdk) that provides a Plugin Development Kit (PDK) and a standalone plugin server to enable writing Kong Gateway plugins in JavaScript.
- Its main features are:
- A CLI/binary (`bin/kong-js-pluginserver` / `cli.js`) to launch the server.
- A runtime (`server.js`, `listener.js`) that speaks Kong’s plugin-server protocol.
- A JavaScript PDK (`lib/*.js` + `kong/*.d.ts`) exposing Kong contexts and actions.
- Example plugins and tests demonstrating how to integrate.

##### File structure
- Top-level
- Configuration & metadata: `.babelrc`, `.eslintrc.js`, `package.json`, GitHub workflows, changelog, etc.
- Entry points: `cli.js` (CLI wrapper) and `bin/kong-js-pluginserver` (shell shim).
- Runtime code: `server.js` (HTTP/TCP listener), `listener.js` (handles incoming RPC).
- PDK implementation: `lib/mod.js`, `lib/pipe.js`, plus `pdk.js` (exports PDK API).
- Type definitions: `kong/*.d.ts` for every Kong context (request, response, router, etc.).
- Examples and tests under `examples/` and `__tests__/`.

##### README for additional insights
- Confirms it’s a plugin server + PDK for JavaScript support in Kong (>= 2.3.0).
- Points to Kong Docs for usage and plugin lifecycle.
- Mentions future work (TypeScript rewrite, per-plugin server).

##### Main components
a. Kong Gateway (external service)
b. CLI / Plugin Server launcher
c. Plugin Server process
- Listener (TCP/HTTP)
- RPC handler
- PDK core modules
- User plugin code
d. User plugins (examples/js-*)
e. (Optional) Test harness & examples

##### Relationships and interactions
- The operator runs `kong-js-pluginserver` (CLI) to start the Plugin Server.
- Kong Gateway (configured with `config.lua` pointing at the server’s address) makes RPC calls to the server for each plugin hook (e.g., `access`, `header_filter`).
- Listener accepts each RPC request, invokes the PDK layer (`lib/mod.js` + type definitions) to expose Kong contexts.
- PDK calls are routed into the user’s plugin code.
- Plugin code uses PDK APIs to read request/response, call upstream services, mutate headers, etc.
- The PDK serializes the result, sends a response back over the same RPC channel to Kong.

##### Architectural patterns and principles
- **Plugin Architecture**: decouples Kong core from custom logic via an RPC boundary.
- **Adapter/Facade**: PDK modules expose a friendly JS API over Kong’s low-level RPC protocol.
- **Separation of Concerns**: Listener → PDK core → User plugin code.
- **Extensibility**: New hooks or contexts can be added by extending `kong/*.d.ts` and `lib/` modules.

##### Detail level
- **every** major module: `server.js`, `listener.js`, `lib/mod.js`, type definitions in `kong/`, and how they chain.
- How `cli.js`/`bin` bootstraps `server.js`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External System
    KG["Kong Gateway"]:::external

    %% CLI / Launcher
    subgraph "CLI / Launcher"
        CLI1["cli.js"]:::cli
        CLI2["bin/kong-js-pluginserver"]:::cli
    end

    %% Plugin Server Process
    subgraph "Plugin Server Process"
        Srv["server.js"]:::runtime
        Lis["listener.js"]:::runtime
    end

    %% PDK Core Modules
    subgraph "PDK Core Modules"
        Mod["lib/mod.js"]:::pdk
        Pipe["lib/pipe.js"]:::pdk
        PDK["pdk.js"]:::pdk
    end

    %% Type Definitions
    subgraph "Type Definitions"
        Types["kong/"]:::types
    end

    %% User Plugins
    subgraph "User Plugins"
        EX1["examples/js-goodbye"]:::plugins
        EX2["examples/js-graphql"]:::plugins
        EX3["examples/js-hello.js"]:::plugins
        EX4["examples/js-status.js"]:::plugins
        EX5["examples/js-transform.js"]:::plugins
        EX6["examples/ts-hello.ts"]:::plugins
    end

    %% Tests & Demonstrations
    subgraph "Tests & Demonstrations"
        PT["plugin_test.js"]:::tests
        TST["__tests__/"]:::tests
    end

    %% Data Flow
    CLI2 -->|"shim"| CLI1
    CLI1 -->|"bootstrap"| Srv
    Srv -->|"initializes"| Lis
    KG -->|"gRPC/HTTP RPC calls"| Lis
    Lis -->|"decode RPC"| Mod
    Mod -->|"I/O plumbing"| Pipe
    Mod -->|"exports API"| PDK
    Mod -->|"type bindings"| Types
    Mod -->|"invoke hook"| EX1
    Mod -->|"invoke hook"| EX2
    Mod -->|"invoke hook"| EX3
    Mod -->|"invoke hook"| EX4
    Mod -->|"invoke hook"| EX5
    Mod -->|"invoke hook"| EX6
    EX1 -->|"return result"| Mod
    EX2 -->|"return result"| Mod
    EX3 -->|"return result"| Mod
    EX4 -->|"return result"| Mod
    EX5 -->|"return result"| Mod
    EX6 -->|"return result"| Mod
    Mod -->|"encode RPC"| Lis
    Lis -->|"send response"| KG

    PT -->|"test plugin calls"| Mod
    TST -->|"unit/integration tests"| Mod

    %% Click Events
    click CLI1 "https://github.com/kong/kong-js-pdk/blob/master/cli.js"
    click CLI2 "https://github.com/kong/kong-js-pdk/tree/master/bin/kong-js-pluginserver"
    click Srv "https://github.com/kong/kong-js-pdk/blob/master/server.js"
    click Lis "https://github.com/kong/kong-js-pdk/blob/master/listener.js"
    click Mod "https://github.com/kong/kong-js-pdk/blob/master/lib/mod.js"
    click Pipe "https://github.com/kong/kong-js-pdk/blob/master/lib/pipe.js"
    click PDK "https://github.com/kong/kong-js-pdk/blob/master/pdk.js"
    click Types "https://github.com/kong/kong-js-pdk/tree/master/kong/"
    click EX1 "https://github.com/kong/kong-js-pdk/tree/master/examples/js-goodbye"
    click EX2 "https://github.com/kong/kong-js-pdk/tree/master/examples/js-graphql"
    click EX3 "https://github.com/kong/kong-js-pdk/blob/master/examples/js-hello.js"
    click EX4 "https://github.com/kong/kong-js-pdk/blob/master/examples/js-status.js"
    click EX5 "https://github.com/kong/kong-js-pdk/blob/master/examples/js-transform.js"
    click EX6 "https://github.com/kong/kong-js-pdk/blob/master/examples/ts-hello.ts"
    click PT "https://github.com/kong/kong-js-pdk/blob/master/plugin_test.js"
    click TST "https://github.com/kong/kong-js-pdk/tree/master/__tests__/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef runtime fill:#bfb,stroke:#333,stroke-width:1px
    classDef pdk fill:#ffb,stroke:#333,stroke-width:1px
    classDef types fill:#fbf,stroke:#333,stroke-width:1px
    classDef plugins fill:#fb8,stroke:#333,stroke-width:1px
    classDef tests fill:#fbb,stroke:#333,stroke-width:1px
```
