How national-digital-twin/management-node works
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