# national-digital-twin/management-node architecture

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

- Interactive diagram: https://gitdiagram.com/national-digital-twin/management-node
- Repository: https://github.com/national-digital-twin/management-node

## Overview

##### Project type and purpose
- This is a standalone Spring Boot “Management Node” microservice that provides REST APIs for dynamic configuration management.
- The APIs are consumed by two types of external clients (“Producer Federator” and “Consumer Federator”).
- It secures all communications using Mutual TLS (MTLS) and delegates authentication/authorization to Keycloak (OAuth2 Resource Server with JWT introspection).

##### File structure
- Top-level directories and files:
- src/main/java: Java code organized by package into config, controller, converter, exception, model, persistency, service (data + providers).
- src/main/resources: application.yml, database migration scripts, sample data.
- docker: Dockerfile for the Management Node, docker/keycloak for spinning up Keycloak+PostgreSQL via Docker Compose, terraform modules for repository configuration.
- .github/workflows and .github/actions: CI/CD pipelines (Maven build, Docker publish, OSS checks).
- pom.xml: Maven build, dependencies (Spring Boot, Spring Data JPA, Spring Security OAuth2, springdoc-openapi, etc.).
- Architectural choices visible: layered MVC (controller → service → repository), JPA-based persistence, database migrations, zero-trust MTLS, external IAM integration.

##### Leverage the README insights
- “Zero-trust connectivity”: all service-to-service calls run over MTLS.
- Keycloak as OAuth2/JWT identity provider.
- PostgreSQL for persistence, with Flyway‐style migrations under src/main/resources/db/migration.
- Docker Compose for local Keycloak+DB, Terraform for cloud infra.
- OpenAPI documentation via springdoc.

##### Main components & relationships
a. External Clients (Producer Federator, Consumer Federator)
- These run outside the service boundary, each holding a client certificate.
- They communicate over HTTPS+MTLS to produce or consume configurations.
b. Management Node Microservice
- Ingress Layer (Spring MVC Controllers)
- Security Layer (Spring Security configured for MTLS & JWT token introspection via Keycloak endpoint)
- Service Layer (business logic: ConfigurationProvider implementations + data services)
- Data Access Layer (Spring Data JPA repositories, entity-DTO converters)
- Database Migration Subsystem (scripts under db/migration)
c. Keycloak Identity Provider
- Exposes HTTPS MTLS endpoints for token issuance and introspection.
- Holds realm and client configuration imported via docker/keycloak/management-node-realm.json.
d. PostgreSQL Database
- Stores entities: Producer, Consumer, Product, ProductConsumer, Attributes, Organisation, etc.
- Accessed via JDBC over TLS (if configured) by the microservice.
e. Infrastructure Provisioning
- Terraform modules in docker/keycloak/tofu and repository-configuration.
- Orchestrates Keycloak and DB in cloud environments.
f. CI/CD & Docker
- GitHub Actions triggering Maven build, Docker image build, publishing to GitHub Container Registry.

Interactions:
1. Federator → Management Node: TLS mutual auth, REST calls (/api/v1/configuration/{producer|consumer}).
2. Management Node → Keycloak: TLS mutual auth or HTTPS call for JWT introspection / token retrieval.
3. Management Node → PostgreSQL: JDBC read/write for configuration data.
4. CI/CD pipelines push Docker images used by both Management Node and Keycloak.
5. Terraform provisions Keycloak & Postgres.

##### Architectural patterns & principles
- Layered architecture (Controller → Service → Repository)
- Zero-trust security (Mutual TLS, JWT Bearer tokens)
- Externalized configuration (Spring profiles, application-{profile}.yml)
- Infrastructure as Code (Terraform, Docker Compose)
- Automated database versioning (migration scripts)
- OpenAPI specification for discoverability

## Diagram (Mermaid)

```mermaid
graph TD

subgraph "External Clients"
  ProdFed["Producer Federator"]:::client
  ConsFed["Consumer Federator"]:::client
end

subgraph "Management Node"
  MNApp["ManagementNodeApplication"]:::management
  subgraph "Ingress Layer"
    ConfigController["ConfigurationController"]:::management
  end
  subgraph "Security Layer"
    SecConfig["SecurityConfig"]:::management
    JwtConv["KeycloakJwtAuthenticationConverter"]:::management
    JwtToken["CustomJwtAuthenticationToken"]:::management
    SslInit["SslPropertyInitializer"]:::management
    MdcFilter["ClientIdMdcFilter"]:::management
  end
  subgraph "Service Layer"
    DataSvcInt["Data Services Interfaces"]:::management
    DataSvcImpl["Data Services Implementations"]:::management
    ConfigProvInt["ConfigurationProvider"]:::management
    ConfigProvImpl["ConfigurationProviderImpl"]:::management
  end
  subgraph "Data Access Layer"
    Entities["JPA Entities"]:::management
    Repos["Spring Data Repositories"]:::management
    ConvInt["EntityDtoConverter"]:::management
    ConvImpl["Converter Implementations"]:::management
  end
  subgraph "Database Migration"
    Flyway["Flyway Scripts"]:::management
    Samples["Sample Data Scripts"]:::management
  end
  subgraph "Configuration"
    AppConfig["application.yml"]:::management
    OpenApi["OpenApiConfig"]:::management
  end
end

Keycloak["Keycloak Identity Provider"]:::idp
Postgres["PostgreSQL Database"]:::db

CI["CI/CD Pipelines"]:::doc
Terraform["Terraform Modules"]:::doc

DockerMN["Management Node Docker Image"]:::doc
DockerKC["Keycloak & DB Docker Compose"]:::doc

ProdFed -->|HTTPS+MTLS| ConfigController
ConsFed -->|HTTPS+MTLS| ConfigController
ConfigController -->|calls| SecConfig
SecConfig -->|JWT introspection / MTLS| Keycloak
ConfigController -->|invokes| DataSvcInt
DataSvcInt -->|implemented by| DataSvcImpl
DataSvcImpl -->|uses| ConfigProvImpl
ConfigProvImpl -->|reads/writes| Repos
Repos -->|performs| Entities
Entities -->|persist via JDBC over TLS| Postgres
ConvInt -->|implemented by| ConvImpl
Flyway -->|migration at startup| Postgres
Samples -->|load sample data| Postgres
AppConfig -->|provides config| MNApp
OpenApi -->|generates docs| MNApp

CI -->|build & test| DockerMN
CI -->|publish| DockerMN
CI -->|release| DockerKC
Terraform -->|provisions| Keycloak
Terraform -->|provisions| Postgres
DockerKC -->|local env| Keycloak & Postgres

click ConfigController "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/controller/v1/ConfigurationController.java"
click SecConfig "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/SecurityConfig.java"
click JwtConv "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/KeycloakJwtAuthenticationConverter.java"
click JwtToken "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/CustomJwtAuthenticationToken.java"
click SslInit "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/SslPropertyInitializer.java"
click MdcFilter "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/ClientIdMdcFilter.java"
click DataSvcInt "https://github.com/national-digital-twin/management-node/tree/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/service/data"
click DataSvcImpl "https://github.com/national-digital-twin/management-node/tree/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/service/data/impl"
click ConfigProvInt "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/service/providers/configuration/ConfigurationProvider.java"
click ConfigProvImpl "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/service/providers/configuration/ConfigurationProviderImpl.java"
click Entities "https://github.com/national-digital-twin/management-node/tree/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/persistency/entity"
click Repos "https://github.com/national-digital-twin/management-node/tree/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/persistency/repository"
click ConvInt "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/converter/EntityDtoConverter.java"
click ConvImpl "https://github.com/national-digital-twin/management-node/tree/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/converter/impl"
click Flyway "https://github.com/national-digital-twin/management-node/tree/main/src/main/resources/db/migration"
click Samples "https://github.com/national-digital-twin/management-node/tree/main/src/main/resources/db/samples"
click AppConfig "https://github.com/national-digital-twin/management-node/blob/main/src/main/resources/application.yml"
click OpenApi "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/config/OpenApiConfig.java"
click DockerKC "https://github.com/national-digital-twin/management-node/blob/main/docker/keycloak/docker-compose.yml"
click Terraform "https://github.com/national-digital-twin/management-node/blob/main/docker/keycloak/tofu/realm.tf"
click DockerMN "https://github.com/national-digital-twin/management-node/tree/main/docker/Dockerfile"
click DockerMN "https://github.com/national-digital-twin/management-node/tree/main/docker/Dockerfile-dev"
click DockerMN "https://github.com/national-digital-twin/management-node/blob/main/docker/build.sh"
click CI "https://github.com/national-digital-twin/management-node/blob/main/.github/workflows/maven.yml"
click CI "https://github.com/national-digital-twin/management-node/blob/main/.github/workflows/docker-ghcr.yml"
click CI "https://github.com/national-digital-twin/management-node/blob/main/.github/workflows/release.yaml"
click CI "https://github.com/national-digital-twin/management-node/blob/main/.github/workflows/oss-checker.yml"
click CI "https://github.com/national-digital-twin/management-node/blob/main/.github/workflows/publish-github-release.yml"
click MNApp "https://github.com/national-digital-twin/management-node/blob/main/src/main/java/uk/gov/dbt/ndtp/ia/node/management/ManagementNodeApplication.java"

classDef client fill:#BC80BD,shape:ellipse
classDef management fill:#B3CDE0,shape:rect
classDef db fill:#CCEBC5,shape:cylinder
classDef idp fill:#fdae61,shape:cloud
classDef doc fill:#f0e68c,shape:rect
```
