Spring Boot microservices architecture

Registry-driven architecture for Spring Boot microservices

Spring Middleware defines a platform architecture for Spring Boot microservices. It introduces a control plane for service discovery and topology, and a data plane for service communication, GraphQL federation, tracing, and error handling. Infrastructure concerns are standardized while services remain autonomous.

Read documentation View GraphQL federation
Control plane + data plane Service discovery Registry-driven topology Declarative HTTP clients GraphQL federation Tracing + unified errors Kafka / RabbitMQ / Redis / Mongo / JPA

What this architecture does

Spring Middleware is not a hidden runtime that takes over service design. It acts as a platform layer that centralizes repeated infrastructure concerns so teams do not have to rebuild discovery, client wiring, schema metadata, tracing, messaging setup, and error normalization in every service.

Application business logic
Spring Middleware platform layer
Spring Boot / transport / infrastructure

Design goals

The architecture is designed to make cross-cutting concerns reusable without hiding the actual system shape. Services remain autonomous, but infrastructure behavior becomes consistent across the platform.

  • Centralize cross-cutting concerns without hiding architecture behind framework magic.
  • Keep services autonomous and focused on domain ownership.
  • Standardize infrastructure behavior across communication, discovery, errors, tracing, security, and integration.

See also the security guide for the platform authentication and authorization model.

Control plane and data plane

The architecture separates topology and metadata management from runtime service execution. The Registry acts as the control plane, while services operate in the data plane through shared platform conventions.

Control plane

The Registry Service maintains service topology, registered REST metadata, GraphQL schema locations, node endpoints, and health-related cleanup.

Service topology REST metadata Schema locations Node health

Data plane

Application services expose APIs, call each other through declarative clients, share the same tracing and error model, and use reusable infrastructure modules.

Declarative HTTP GraphQL federation Redis / Mongo / JPA Kafka / RabbitMQ

High-level topology

Services register themselves in the control plane and consume each other through registry-resolved communication. The topology remains explicit instead of being hidden inside framework configuration.

Registry Service

Control plane for topology, REST metadata, GraphQL schema locations, and runtime discovery.

Catalog Service

Registers resources and consumes downstream services through registry-driven resolution.

Product Service

Publishes service metadata and exposes domain APIs and GraphQL capabilities.

Reference Service

Participates in the same platform model with shared tracing, errors, and infrastructure modules.

Core concepts

The platform is built around a small set of explicit concepts that define topology, registration, and runtime communication.

Cluster and node

A cluster is the logical service identity, such as product-service or catalog-service. A node is a concrete runtime instance of that cluster, such as a pod, container, or VM.

Registry

The Registry stores service topology, REST metadata, GraphQL schema locations, and node health information so runtime discovery remains explicit and centralized.

Resources and schemas

A resource is a registered REST endpoint. A schema is a GraphQL definition published by a service for discovery, composition, and federation.

Declarative clients

@MiddlewareClient defines a declarative remote contract. The platform resolves targets through the Registry, selects nodes, propagates context, and normalizes remote failures consistently.

Service communication flow

Runtime calls are routed through declarative interfaces, registry lookup, node selection, and standardized request and response handling.

01

Invoke declarative client

Application code calls an interface annotated with @MiddlewareClient.

02

Resolve service identity

The target cluster is resolved from client metadata.

03

Lookup nodes

The Registry returns available nodes and the platform selects a target endpoint.

04

Execute request

WebClient sends the request with propagated identifiers such as X-Request-ID and X-Span-ID.

05

Normalize response

Responses are mapped to the contract and failures are normalized into the platform error model.

Convergence and self-healing

The Registry is not treated as a permanently correct source of truth. Services continuously reconcile their own presence and metadata so the platform converges back to the real cluster state after failures.

What services verify

  • Node endpoint presence in the Registry
  • REST resource registration
  • GraphQL schema registration
  • Required messaging infrastructure

What the platform restores

  • Missing REST metadata
  • Missing GraphQL schema entries
  • Lost node endpoints
  • Node-scoped queues and bindings

Error and tracing model

Spring Middleware defines a consistent error structure and lightweight tracing so teams can correlate behavior across services without depending on heavy platform assumptions.

Structured errors

The platform standardizes failure handling through types such as ServiceException, ErrorDescriptor, and a shared remote error model across HTTP and GraphQL boundaries. 

{
  "statusCode": 404,
  "code": "PRODUCT:NOT_FOUND",
  "message": "Product not found"
}

Tracing and correlation

Every request participates in correlation through X-Request-ID and span identifiers. The goal is explicit observability and easier log correlation across synchronous and GraphQL flows.

Module architecture

Spring Middleware is published as a multi-module ecosystem managed through a BOM and organized by platform concern.

Core modules

commons, api, app, model-api, model-core

Data modules

mongo-*, jpa-*, redis-*, cache

Messaging and platform

rabbitmq, kafka, registry-*, graphql

Typical dependency flow

boot
core
api

Consumption model

Consumers import the BOM and depend only on the modules they need. Contributors work inside the parent multi-module repository, but the published model stays modular and explicit.

Next steps

Continue through the platform

Explore the related guides and capability pages to understand how this part of Spring Middleware fits into the broader runtime model.

Modules Open documentation