# bytegitaccnt/nexusgate architecture

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

- Interactive diagram: https://gitdiagram.com/bytegitaccnt/nexusgate
- Repository: https://github.com/bytegitaccnt/nexusgate

## Overview

NexusGate is a reactive API gateway: it loads service and policy configuration, builds routes, applies authentication and optional rate limits, rewrites permitted management requests, then proxies traffic to downstream services. The principal request workflow and the documented outer-IP and inner-user limiter branches are represented. Some configuration, management-filter, and security wiring is documented or evident from the tree but was not sampled; those links are shown only where the README or sampled callers support them.

Main entry points: [`src/main/java/com/nexusgate/nexus_gateway/Config/NexusRouteBuilder.java`](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/NexusRouteBuilder.java) (Route builder), [`src/main/java/com/nexusgate/nexus_gateway/Filter/OuterRateLimitFilter.java`](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/OuterRateLimitFilter.java) (Outer IP limiter), [`src/main/java/com/nexusgate/nexus_gateway/Filter/InnerRateLimitGatewayFilterFactory.java`](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/InnerRateLimitGatewayFilterFactory.java) (Inner user limiter), [`src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RedisTokenBucket.java`](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RedisTokenBucket.java) (Token bucket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing and config"]
  node_app["Gateway application"]
  node_yaml["Gateway YAML<br/>[nexus.yml]"]
  node_config["Config loader"]
  node_routebuilder["Route builder"]
  node_serviceconfig["Service settings<br/>[ServiceConfig.java]"]
end

subgraph group_security["Authentication"]
  node_jwtfilter["JWT route filter"]
  node_verifier["JWT verifier"]
  node_securityconfig["JWT settings<br/>[JwtConfig.java]"]
end

subgraph group_limits["Rate limiting"]
  node_outer["Outer IP limiter"]
  node_inner["Inner user limiter"]
  node_ipresolver["Client IP resolver"]
  node_keygen["Rate-limit keys"]
end

subgraph group_management["Management access"]
  node_managementconfig["Management settings"]
  node_managementfilter["Management filter"]
end

subgraph group_redis["Redis state"]
  node_bucket["Token bucket"]
  node_redis[("Redis")]
  node_lua["Bucket script<br/>[token_bucket.lua]"]
end

node_client(("Client"))
node_downstream["Downstream services"]

node_app -->|"starts gateway"| node_routebuilder
node_yaml -->|"configures"| node_config
node_routebuilder -->|"loads config"| node_config
node_config -->|"binds services"| node_serviceconfig
node_routebuilder -->|"attaches filter"| node_jwtfilter
node_routebuilder -->|"attaches limiter"| node_inner
node_routebuilder -->|"reads policy"| node_managementconfig
node_routebuilder -->|"attaches filter"| node_managementfilter
node_client -->|"sends request"| node_outer
node_outer -->|"resolves IP"| node_ipresolver
node_outer -->|"creates IP key"| node_keygen
node_inner -->|"creates user key"| node_keygen
node_inner -->|"consumes tokens"| node_bucket
node_outer -->|"consumes tokens"| node_bucket
node_jwtfilter -->|"verifies token"| node_verifier
node_verifier -->|"reads settings"| node_securityconfig
node_bucket -->|"executes script"| node_lua
node_bucket -->|"reads and writes"| node_redis
node_jwtfilter -->|"forwards request"| node_downstream
node_managementfilter -->|"forwards request"| node_downstream
node_outer -->|"continues chain"| node_downstream
node_inner -->|"continues chain"| node_downstream
node_downstream -->|"returns response"| node_client

click node_app "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/NexusGatewayApplication.java"
click node_yaml "https://github.com/bytegitaccnt/nexusgate/blob/main/nexus.yml"
click node_config "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/NexusConfigLoader.java"
click node_routebuilder "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/NexusRouteBuilder.java"
click node_serviceconfig "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/ServiceConfig.java"
click node_jwtfilter "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/JwtAuthenticationGatewayFilterFactory.java"
click node_verifier "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/Security/HmacJwtTokenVerifier.java"
click node_securityconfig "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/Security/JwtConfig.java"
click node_outer "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/OuterRateLimitFilter.java"
click node_inner "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/InnerRateLimitGatewayFilterFactory.java"
click node_ipresolver "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/ClientIpResolver.java"
click node_keygen "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RateLimitKeyGenerator.java"
click node_bucket "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RedisTokenBucket.java"
click node_lua "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/resources/redis/token_bucket.lua"
click node_managementconfig "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/management/ManagementConfig.java"
click node_managementfilter "https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/ManagementEndpointGatewayFilterFactory.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_app,node_yaml,node_config,node_routebuilder,node_serviceconfig,node_client toneBlue
class node_jwtfilter,node_verifier,node_securityconfig toneAmber
class node_outer,node_inner,node_ipresolver,node_keygen toneMint
class node_managementconfig,node_managementfilter toneRose
class node_bucket,node_redis,node_lua,node_downstream toneIndigo
```

## Components

### Routing and config

- [Gateway application](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/NexusGatewayApplication.java): `src/main/java/com/nexusgate/nexus_gateway/NexusGatewayApplication.java`
- [Gateway YAML](https://github.com/bytegitaccnt/nexusgate/blob/main/nexus.yml): `nexus.yml`
- [Config loader](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/NexusConfigLoader.java): `src/main/java/com/nexusgate/nexus_gateway/Config/NexusConfigLoader.java`
- [Route builder](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/NexusRouteBuilder.java): `src/main/java/com/nexusgate/nexus_gateway/Config/NexusRouteBuilder.java`
- [Service settings](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/ServiceConfig.java): `src/main/java/com/nexusgate/nexus_gateway/Config/ServiceConfig.java`

### Authentication

- [JWT route filter](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/JwtAuthenticationGatewayFilterFactory.java): `src/main/java/com/nexusgate/nexus_gateway/Filter/JwtAuthenticationGatewayFilterFactory.java`
- [JWT verifier](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/Security/HmacJwtTokenVerifier.java): `src/main/java/com/nexusgate/nexus_gateway/Config/Security/HmacJwtTokenVerifier.java`
- [JWT settings](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/Security/JwtConfig.java): `src/main/java/com/nexusgate/nexus_gateway/Config/Security/JwtConfig.java`

### Rate limiting

- [Outer IP limiter](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/OuterRateLimitFilter.java): `src/main/java/com/nexusgate/nexus_gateway/Filter/OuterRateLimitFilter.java`
- [Inner user limiter](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/InnerRateLimitGatewayFilterFactory.java): `src/main/java/com/nexusgate/nexus_gateway/Filter/InnerRateLimitGatewayFilterFactory.java`
- [Client IP resolver](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/ClientIpResolver.java): `src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/ClientIpResolver.java`
- [Rate-limit keys](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RateLimitKeyGenerator.java): `src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RateLimitKeyGenerator.java`

### Management access

- [Management settings](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/management/ManagementConfig.java): `src/main/java/com/nexusgate/nexus_gateway/Config/management/ManagementConfig.java`
- [Management filter](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Filter/ManagementEndpointGatewayFilterFactory.java): `src/main/java/com/nexusgate/nexus_gateway/Filter/ManagementEndpointGatewayFilterFactory.java`

### Redis state

- [Token bucket](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RedisTokenBucket.java): `src/main/java/com/nexusgate/nexus_gateway/Config/RateLimit/RedisTokenBucket.java`
- **Redis**
- [Bucket script](https://github.com/bytegitaccnt/nexusgate/blob/main/src/main/resources/redis/token_bucket.lua): `src/main/resources/redis/token_bucket.lua`

### Other components

- **Client**
- **Downstream services**

## Connections

- Gateway application → Route builder: starts gateway
- Gateway YAML → Config loader: configures
- Route builder → Config loader: loads config
- Config loader → Service settings: binds services
- Route builder → JWT route filter: attaches filter
- Route builder → Inner user limiter: attaches limiter
- Route builder → Management settings: reads policy
- Route builder → Management filter: attaches filter
- Client → Outer IP limiter: sends request
- Outer IP limiter → Client IP resolver: resolves IP
- Outer IP limiter → Rate-limit keys: creates IP key
- Inner user limiter → Rate-limit keys: creates user key
- Inner user limiter → Token bucket: consumes tokens
- Outer IP limiter → Token bucket: consumes tokens
- JWT route filter → JWT verifier: verifies token
- JWT verifier → JWT settings: reads settings
- Token bucket → Bucket script: executes script
- Token bucket → Redis: reads and writes
- JWT route filter → Downstream services: forwards request
- Management filter → Downstream services: forwards request
- Outer IP limiter → Downstream services: continues chain
- Inner user limiter → Downstream services: continues chain
- Downstream services → Client: returns response