# solaceproducts/solace-spring-cloud architecture

> Architecture diagram of the GitHub repository solaceproducts/solace-spring-cloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solaceproducts/solace-spring-cloud
- Repository: https://github.com/solaceproducts/solace-spring-cloud

## Overview

##### Project type and purpose
- This is an open-source, multi-module Maven library (“umbrella project”) that provides Spring Cloud Stream Binder support for Solace PubSub+ messaging.
- Its main use case is to plug into Spring Cloud Stream applications so they can bind input and output channels to a Solace broker.

##### File structure
- Top-level aggregator: `pom.xml` with modules:
– `solace-spring-cloud-bom`: Bill of Materials for version alignment
– `solace-spring-cloud-parent`: common dependency management and plugin configuration
– `solace-spring-cloud-starters/solace-spring-cloud-stream-starter`: Spring Boot Starter that triggers binder auto-configuration
– `solace-spring-cloud-stream-binder-core`: core implementation of the `Binder` SPI for Solace
– `solace-spring-cloud-stream-binder`: higher-level binder wiring and configuration templates
– `solace-spring-cloud-stream-binder-opentelemetry`: optional instrumentation module for OpenTelemetry
- Each module is a Maven sub-project with its own `pom.xml`, `src/main/java`, `src/test` etc.

##### Key insights from the README
- Describes an umbrella build: “build everything with `mvn package`”
- Clarifies which modules are user-facing (starter, binder) versus build-only (BOM, parent)
- Mentions external integration points: Spring Cloud Stream, Solace PubSub+ broker, Docker for integration tests, OpenTelemetry for instrumentation

##### Main components
a. Spring Cloud Stream Framework (external)
b. Spring Boot Auto-Configuration / Starter (`solace-spring-cloud-stream-starter`)
c. Binder SPI implementation (`solace-spring-cloud-stream-binder-core` + `solace-spring-cloud-stream-binder`)
d. Optional Instrumentation Module (`solace-spring-cloud-stream-binder-opentelemetry`)
e. Solace PubSub+ Broker (external)
f. JCSMP API (Solace Java API)
g. Maven Aggregator and BOM/Parent POM (build-time modules)

##### Relationships and interactions
- The Starter auto-configures Spring Cloud Stream to use the Solace Binder implementation at application startup.
- The Binder modules implement the `Binder` SPI, creating inbound/outbound adapters that use JCSMP under the covers to talk to the Solace broker.
- The BOM and Parent POM propagate consistent versions of Spring Cloud, Spring Boot, and Solace libraries across all modules.
- The instrumentation module attaches OpenTelemetry hooks around binder operations to export traces to an OTEL collector.
- Integration tests spin up a Docker-provisioned broker (or external broker defined by environment variables) to verify end-to-end behavior.

##### Architectural patterns and design principles
- Modular Maven multi-module project (aggregator POM)
- SPI-based Binder pattern from Spring Cloud Stream
- Spring Boot auto-configuration (conditional beans, `@EnableBinding`)
- Dependency management via BOM/Parent POM
- Separation of concerns: starter vs core binder vs instrumentation vs build modules

- Clear labels on each module and external system
– Maven aggregator & version management
– Spring Boot Starter / auto-config modules
– Binder Core
– Instrumentation
– External systems (broker, OTEL collector, Spring Cloud Stream)
- Notes on SPI extension points where the library plugs into Spring Cloud Stream

##### Putting it all together
1. Spring Boot Starter (auto-config)
2. Binder SPI Implementation (core + binder module)
– Off to one side, show the OTEL Collector receiving trace data from the instrumentation module.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build & Version Management
    subgraph "Build & Version Management"
        MavenAggregator["Maven Aggregator (pom.xml)"]:::build
        BOM["Bill of Materials (BOM) Module"]:::build
        Parent["Parent POM Module"]:::build
    end

    %% Application Runtime
    subgraph "Application Runtime"
        Starter["Spring Boot Starter (auto-configuration)"]:::runtime
        BinderCore["Binder SPI Core Implementation"]:::runtime
        BinderWiring["Binder Wiring & Configuration Templates"]:::runtime
        Instrumentation["OpenTelemetry Instrumentation Module"]:::optional
        InstrumentationTests["Instrumentation Integration Tests"]:::runtime
        IntegrationTestSupport["Integration Test Support Utilities"]:::runtime
    end

    %% External Systems
    subgraph "External Systems"
        SpringCloud["Spring Cloud Stream Framework"]:::external
        JCSMP["JCSMP API"]:::external
        SolaceBroker["Solace PubSub+ Broker"]:::external
        OTEL["OpenTelemetry Collector"]:::external
    end

    %% Dependencies and Data Flow
    MavenAggregator --> BOM
    MavenAggregator --> Parent

    BOM --> Starter
    BOM --> BinderCore
    BOM --> BinderWiring
    BOM --> Instrumentation
    BOM --> InstrumentationTests

    Parent --> Starter
    Parent --> BinderCore
    Parent --> BinderWiring
    Parent --> Instrumentation
    Parent --> InstrumentationTests

    SpringCloud -->|"auto-config binds"| Starter
    Starter -->|"implements Binder SPI"| BinderCore
    Starter -->|"config templates"| BinderWiring
    BinderCore -->|"uses JCSMP API"| JCSMP
    BinderWiring -->|"uses JCSMP API"| JCSMP
    JCSMP -->|"connects to"| SolaceBroker

    BinderCore -->|"instrumentation hooks"| Instrumentation
    BinderWiring -->|"instrumentation hooks"| Instrumentation
    Instrumentation -->|"exports traces to"| OTEL

    IntegrationTestSupport --> InstrumentationTests
    InstrumentationTests -->|"integration tests with"| SolaceBroker

    %% Click Events
    click MavenAggregator "https://github.com/solaceproducts/solace-spring-cloud/blob/master/pom.xml"
    click BOM "https://github.com/solaceproducts/solace-spring-cloud/blob/master/solace-spring-cloud-bom/pom.xml"
    click Parent "https://github.com/solaceproducts/solace-spring-cloud/blob/master/solace-spring-cloud-parent/pom.xml"
    click Starter "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-spring-cloud-starters/solace-spring-cloud-stream-starter"
    click BinderCore "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-spring-cloud-stream-binder/solace-spring-cloud-stream-binder-core"
    click BinderWiring "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-spring-cloud-stream-binder/solace-spring-cloud-stream-binder"
    click Instrumentation "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-spring-cloud-stream-binder-opentelemetry/solace-spring-cloud-stream-binder-instrumentation"
    click InstrumentationTests "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-spring-cloud-stream-binder-opentelemetry/solace-spring-cloud-stream-binder-instrumentation-tests"
    click JCSMP "https://github.com/solaceproducts/solace-spring-cloud/blob/master/src/main/java/com/solace/spring/cloud/stream/binder/inbound/JCSMPInboundChannelAdapter.java"
    click IntegrationTestSupport "https://github.com/solaceproducts/solace-spring-cloud/tree/master/solace-integration-test-support"

    %% Styles
    classDef build fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef runtime fill:#d9edf7,stroke:#31708f,stroke-width:1px
    classDef external fill:#fcf8e3,stroke:#8a6d3b,stroke-width:1px
    classDef optional fill:#f9f2f4,stroke:#c7254e,stroke-dasharray:5 5,stroke-width:1px
```
