# jhipster/jhipster-sample-app-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/jhipster/jhipster-sample-app-gateway
- Repository: https://github.com/jhipster/jhipster-sample-app-gateway

## Overview

#### Purpose and entry points
This is a JHipster 9 gateway in a microservice architecture: it serves an Angular SPA, owns user/authority administration, authenticates clients, and routes requests to discovered backend services. Spring Boot starts at `src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java`; the browser app starts at `src/main/webapp/main.ts` and is composed from `src/main/webapp/app/app.ts`.

#### Gateway runtime and service boundary
The Java runtime is reactive Spring Boot/WebFlux, with gateway routing exposed through `src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java`. Service discovery and centralized configuration are mandatory through Consul; bootstrap/profile configuration is in `src/main/resources/config/bootstrap.yml`, `src/main/resources/config/bootstrap-prod.yml`, and `src/main/docker/consul.yml`. The gateway is therefore the boundary between SPA/API clients and downstream microservices rather than the owner of all domain data.

#### HTTP, security, and error pipeline
`SecurityConfiguration.java` establishes server-side access control, while JWT configuration and relay filter support authenticated gateway requests to downstream services: `src/main/java/io/github/jhipster/sample/config/SecurityConfiguration.java`, `src/main/java/io/github/jhipster/sample/config/SecurityJwtConfiguration.java`, `src/main/java/io/github/jhipster/sample/security/jwt/JWTRelayGatewayFilterFactory.java`. REST endpoints for login/account/admin users sit under `src/main/java/io/github/jhipster/sample/web/rest/AuthenticateController.java`, `AccountResource.java`, and `UserResource.java`. `ExceptionTranslator.java` standardizes API failures; `SpaWebFilter.java` handles SPA-oriented web fallback behavior.

#### Identity and persistence
The gateway persists its own users and authorities, rather than the downstream BankAccount entity. Core model and reactive repository boundaries are `src/main/java/io/github/jhipster/sample/domain/User.java`, `src/main/java/io/github/jhipster/sample/domain/Authority.java`, and `src/main/java/io/github/jhipster/sample/repository/UserRepository.java`. `UserService.java` implements account lifecycle and administration, with mail delivery delegated to `MailService.java`. Liquibase owns schema and seed evolution through `src/main/resources/config/liquibase/master.xml` and `src/main/resources/config/liquibase/changelog/00000000000000_initial_schema.xml`; MySQL is provisioned by `src/main/docker/mysql.yml`.

#### Angular SPA and client-side API boundary
Angular routing/configuration originate in `src/main/webapp/app/app.config.ts` and `src/main/webapp/app/app.routes.ts`. Authentication state, JWT use, route guards, and HTTP interception are centralized under `src/main/webapp/app/core/auth/auth-jwt.service.ts`, `src/main/webapp/app/core/auth/user-route-access.service.ts`, and `src/main/webapp/app/core/interceptor/auth.interceptor.ts`. Account and administration screens consume the gateway’s identity/admin APIs; operational UI lives under `src/main/webapp/app/admin/`.

#### Downstream entity integration
The BankAccount UI is a generated client for a separate `jhipsterSampleMicroservice`, not a matching Java domain controller in this repository. Its route/service layer is `src/main/webapp/app/entities/jhipsterSampleMicroservice/bank-account/bank-account.routes.ts` and `src/main/webapp/app/entities/jhipsterSampleMicroservice/bank-account/service/bank-account.service.ts`; entity aggregation is `src/main/webapp/app/entities/entity.routes.ts`. Requests cross the gateway/discovery boundary to the target microservice.

#### Operations and deployment
Profiles configure development/production behavior in `src/main/resources/config/application-dev.yml` and `application-prod.yml`. Docker Compose descriptors provide the application and dependencies: `src/main/docker/app.yml`, `src/main/docker/services.yml`, and `src/main/docker/central-server-config/application.yml`. Observability infrastructure includes Prometheus, Grafana, and Zipkin (`src/main/docker/prometheus/prometheus.yml`, `src/main/docker/grafana/provisioning/datasources/datasource.yml`, `src/main/docker/zipkin.yml`); Hazelcast management is also supplied.

Main entry points: [`src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java`](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java) (Spring Boot gateway), [`src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java`](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java) (Gateway routing), [`src/main/webapp/app/app.ts`](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.ts) (Angular app shell), [`src/main/webapp/app/app.routes.ts`](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.routes.ts) (Routes & app config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spa["Angular SPA"]
  node_browser(("Browser client<br/>[main.ts]"))
  node_angular_app["Angular app shell<br/>[app.ts]"]
  node_spa_routes["Routes &amp; app config<br/>Angular routing<br/>[app.routes.ts]"]
  node_spa_auth["Client auth boundary<br/>JWT, guards, interceptor"]
  node_identity_ui["Account &amp; admin UI<br/>Angular features"]
  node_bank_ui["BankAccount client<br/>generated entity UI"]
end

subgraph group_gateway["Gateway Runtime"]
  node_gateway_app{{"Spring Boot gateway<br/>WebFlux application"}}
  node_security["Security &amp; JWT relay<br/>WebFlux security"]
  node_identity_api["Identity REST APIs<br/>login, account, users"]
  node_gateway_routes["Gateway routing<br/>discovery-backed proxy"]
  node_web_error["SPA fallback &amp; API errors<br/>WebFlux filters<br/>[SpaWebFilter.java]"]
end

subgraph group_identity["Identity Data"]
  node_user_service["User lifecycle service<br/>application service<br/>[UserService.java]"]
  node_user_repository["User repository<br/>reactive repository"]
  node_identity_schema["Users &amp; authorities schema<br/>Liquibase model<br/>[master.xml]"]
  node_mysql[("MySQL<br/>identity database<br/>[mysql.yml]")]
  node_mail["Mail delivery<br/>notification service<br/>[MailService.java]"]
end

subgraph group_platform["Platform &amp; Operations"]
  node_consul{{"Consul<br/>config and discovery<br/>[bootstrap.yml]"}}
  node_downstream{{"jhipsterSampleMicroservice<br/>BankAccount service"}}
  node_operations["Compose &amp; observability<br/>deployment monitoring<br/>[app.yml]"]
end

node_browser -->|"loads"| node_angular_app
node_angular_app -->|"configures"| node_spa_routes
node_spa_routes -->|"navigates"| node_identity_ui
node_spa_routes -->|"navigates"| node_bank_ui
node_angular_app -->|"uses"| node_spa_auth
node_spa_auth -->|"authenticated HTTP"| node_gateway_app
node_identity_ui -->|"identity/admin API"| node_identity_api
node_bank_ui -->|"BankAccount requests"| node_gateway_routes
node_gateway_app -->|"applies"| node_security
node_gateway_app -->|"serves"| node_identity_api
node_gateway_app -->|"proxies through"| node_gateway_routes
node_gateway_app -->|"handles failures/fallback"| node_web_error
node_security -->|"relays JWT"| node_gateway_routes
node_identity_api -->|"account administration"| node_user_service
node_user_service -->|"persists users"| node_user_repository
node_user_service -->|"sends account mail"| node_mail
node_user_repository -->|"reactive access"| node_mysql
node_identity_schema -->|"migrates and seeds"| node_mysql
node_gateway_routes -->|"discovers services"| node_consul
node_gateway_routes -->|"routes BankAccount API"| node_downstream
node_operations -.->|"deploys"| node_gateway_app
node_operations -.->|"provisions"| node_consul

click node_browser "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/main.ts"
click node_angular_app "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.ts"
click node_spa_routes "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.routes.ts"
click node_spa_auth "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/core/auth/auth-jwt.service.ts"
click node_bank_ui "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/entities/jhipsterSampleMicroservice/bank-account/service/bank-account.service.ts"
click node_gateway_app "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java"
click node_security "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/config/SecurityConfiguration.java"
click node_identity_api "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/rest/AuthenticateController.java"
click node_gateway_routes "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java"
click node_web_error "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/filter/SpaWebFilter.java"
click node_user_service "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/service/UserService.java"
click node_user_repository "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/repository/UserRepository.java"
click node_identity_schema "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/resources/config/liquibase/master.xml"
click node_mysql "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/docker/mysql.yml"
click node_mail "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/service/MailService.java"
click node_consul "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/resources/config/bootstrap.yml"
click node_operations "https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/docker/app.yml"

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_browser,node_angular_app,node_spa_routes,node_spa_auth,node_identity_ui,node_bank_ui toneBlue
class node_gateway_app,node_security,node_identity_api,node_gateway_routes,node_web_error toneAmber
class node_user_service,node_user_repository,node_identity_schema,node_mysql,node_mail toneMint
class node_consul,node_downstream,node_operations toneRose
```

## Components

### Angular SPA

- [Browser client](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/main.ts): client · `src/main/webapp/main.ts`
- [Angular app shell](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.ts): Angular · `src/main/webapp/app/app.ts`
- [Routes & app config](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/app.routes.ts): Angular routing · `src/main/webapp/app/app.routes.ts`
- [Client auth boundary](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/core/auth/auth-jwt.service.ts): JWT, guards, interceptor · `src/main/webapp/app/core/auth/auth-jwt.service.ts`
- **Account & admin UI**: Angular features
- [BankAccount client](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/webapp/app/entities/jhipsterSampleMicroservice/bank-account/service/bank-account.service.ts): generated entity UI · Client for a separate microservice. · `src/main/webapp/app/entities/jhipsterSampleMicroservice/bank-account/service/bank-account.service.ts`

### Gateway Runtime

- [Spring Boot gateway](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java): WebFlux application · `src/main/java/io/github/jhipster/sample/JhipsterSampleGatewayApp.java`
- [Security & JWT relay](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/config/SecurityConfiguration.java): WebFlux security · Authenticates clients and relays JWTs downstream. · `src/main/java/io/github/jhipster/sample/config/SecurityConfiguration.java`
- [Identity REST APIs](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/rest/AuthenticateController.java): login, account, users · `src/main/java/io/github/jhipster/sample/web/rest/AuthenticateController.java`
- [Gateway routing](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java): discovery-backed proxy · `src/main/java/io/github/jhipster/sample/web/rest/GatewayResource.java`
- [SPA fallback & API errors](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/web/filter/SpaWebFilter.java): WebFlux filters · `src/main/java/io/github/jhipster/sample/web/filter/SpaWebFilter.java`

### Identity Data

- [User lifecycle service](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/service/UserService.java): application service · `src/main/java/io/github/jhipster/sample/service/UserService.java`
- [User repository](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/repository/UserRepository.java): reactive repository · `src/main/java/io/github/jhipster/sample/repository/UserRepository.java`
- [Users & authorities schema](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/resources/config/liquibase/master.xml): Liquibase model · `src/main/resources/config/liquibase/master.xml`
- [MySQL](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/docker/mysql.yml): identity database · `src/main/docker/mysql.yml`
- [Mail delivery](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/java/io/github/jhipster/sample/service/MailService.java): notification service · `src/main/java/io/github/jhipster/sample/service/MailService.java`

### Platform & Operations

- [Consul](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/resources/config/bootstrap.yml): config and discovery · `src/main/resources/config/bootstrap.yml`
- **jhipsterSampleMicroservice**: BankAccount service · Owns BankAccount domain data.
- [Compose & observability](https://github.com/jhipster/jhipster-sample-app-gateway/blob/main/src/main/docker/app.yml): deployment monitoring · Runs gateway dependencies plus Prometheus, Grafana, and Zipkin. · `src/main/docker/app.yml`

## Connections

- Browser client → Angular app shell: loads
- Angular app shell → Routes & app config: configures
- Routes & app config → Account & admin UI: navigates
- Routes & app config → BankAccount client: navigates
- Angular app shell → Client auth boundary: uses
- Client auth boundary → Spring Boot gateway: authenticated HTTP
- Account & admin UI → Identity REST APIs: identity/admin API
- BankAccount client → Gateway routing: BankAccount requests
- Spring Boot gateway → Security & JWT relay: applies
- Spring Boot gateway → Identity REST APIs: serves
- Spring Boot gateway → Gateway routing: proxies through
- Spring Boot gateway → SPA fallback & API errors: handles failures/fallback
- Security & JWT relay → Gateway routing: relays JWT
- Identity REST APIs → User lifecycle service: account administration
- User lifecycle service → User repository: persists users
- User lifecycle service → Mail delivery: sends account mail
- User repository → MySQL: reactive access
- Users & authorities schema → MySQL: migrates and seeds
- Gateway routing → Consul: discovers services
- Gateway routing → jhipsterSampleMicroservice: routes BankAccount API
- Compose & observability → Spring Boot gateway: deploys
- Compose & observability → Consul: provisions