# operator-framework/java-operator-sdk architecture

> Architecture diagram of the GitHub repository operator-framework/java-operator-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/operator-framework/java-operator-sdk
- Repository: https://github.com/operator-framework/java-operator-sdk

## Overview

##### Project Type and Purpose
- This is a multi-module, Maven-based open-source framework (Java Operator SDK) for building Kubernetes Operators in Java.
- It provides:
- A core runtime library (operator-framework-core)
- An annotation processor (operator-framework)
- A Maven plugin for code bootstrapping (bootstrapper-maven-plugin)
- Support libraries (caffeine-bounded-cache-support, micrometer-support)
- Testing extensions (operator-framework-junit5)
- A BOM POM (operator-framework-bom)
- Sample operators and documentation (sample-operators, docs)

##### File Structure Analysis
- Top-level POM and wrapper files coordinate builds.
- Subdirectories are discrete Maven modules with their own src/, pom.xml, test/, resources.
- “bootstrapper-maven-plugin”: code-generation plugin
- “caffeine-bounded-cache-support” & “micrometer-support”: optional runtime extensions
- “operator-framework-core”: the heart of the controller machinery (event sources, reconciler API, dependent resources, workflows)
- “operator-framework”: compile-time annotation processor generating configuration metadata
- “operator-framework-junit5”: JUnit 5 test harness extensions
- “sample-operators”: example implementations showing best practices
- “docs”: Hugo-based static site for user documentation
- CI/CD: GitHub Actions workflows for build, test, release, site generation

##### Key README Insights
- Emphasis on:
- Kubernetes controller runtime
- Fabric8 client integration
- Batteries-included features (event handling, retries, caching, error handling, observability)
- Mentions related extensions (Quarkus, Spring Boot) but those live in separate repos

a. Main Components
- Developer Toolchain:
- Maven Wrapper & POMs
- bootstrapper-maven-plugin (generates scaffolding)
- annotation processor (operator-framework)
- Core Runtime:
- ControllerManager, Operator, Reconciler API
- EventSourceManager (informer, polling, timer, cache)
- DependentResource framework & Workflow engine
- ConfigurationService & LeaderElectionManager
- Fabric8 Kubernetes Client integration
- Optional Extensions:
- Caffeine Cache support
- Micrometer Metrics support
- Testing:
- JUnit 5 OperatorExtension
- Sample CRDs & in-cluster/locally-run operator tests
- Documentation Site: Hugo pipeline, Netlify
- External Systems: Kubernetes API Server, CRD definitions, Logging/Monitoring backends

b. Relationships & Interactions
- At build time: bootstrapper-plugin + annotation processor generate Java operator scaffolding & CRDs
- OperatorRuntime (core) uses Fabric8 client to watch CRDs via Informers → pushes Events into EventSourceManager → EventProcessor dispatches to Reconciler
- DependentResource & Workflow modules orchestrate secondary resource CRUD operations
- Caffeine & Micrometer modules plug into event-source caching and metrics endpoints
- JUnit5 extension spins up a test cluster (or mocks) and runs Reconciler logic for automated tests
- Docs module is built separately into a website, referencing generated API docs

c. Architectural Patterns & Principles
- Inversion of Control for Reconciler implementations
- Modular design with clear Maven module boundaries
- Plug-in architecture for event sources, caching, metrics
- Compile-time annotation processing to enforce configuration consistency
- Publisher-Subscriber (Informer → EventSource → EventProcessor → Reconciler)
- Reconciliation loop: desired vs actual state

d. Technologies & Frameworks
- Java 8+ (or higher)
- Maven multi-module reactor
- Fabric8 Kubernetes Client
- Caffeine cache
- Micrometer metrics
- JUnit 5
- Hugo (docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Modules
    subgraph "Build-Time" 
        direction TB
        MWP["Maven Wrapper & POMs"]:::build
        BOM["BOM POM (operator-framework-bom)"]:::build
        BBP["bootstrapper-maven-plugin"]:::build
        AP["Annotation Processor"]:::build
    end

    %% Core Runtime
    subgraph "Core Runtime" 
        direction TB
        CM["ControllerManager"]:::runtime
        ESM["EventSourceManager"]:::runtime
        RM["Reconciler API"]:::runtime
        DEM["DependentResource & Workflow Engine"]:::runtime
        LEM["LeaderElectionManager"]:::runtime
        FKC["Fabric8 Kubernetes Client"]:::runtime
    end

    %% Extensions
    subgraph "Optional Extensions" 
        direction TB
        CCS["Caffeine Cache Support"]:::ext
        MMS["Micrometer Metrics Support"]:::ext
    end

    %% Testing
    subgraph "Testing (JUnit5)" 
        direction TB
        J5["OperatorExtension"]:::testing
        TEST["In-Cluster/Local Operator Tests"]:::testing
    end

    %% Documentation
    subgraph "Documentation Site" 
        direction TB
        DOCS["Hugo Static Site"]:::docs
    end

    %% External Systems
    subgraph "External Systems" 
        direction TB
        K8S["Kubernetes API Server"]:::external
        LOG["Logging/Monitoring Backends"]:::external
    end

    %% Build-Time Flow
    MWP -->|"defines modules"| BOM
    BOM -->|"aligns versions"| BBP
    BBP -->|"generates scaffolding"| AP
    AP -->|"produces metadata"| CM

    %% Runtime Flow
    FKC -->|"watches CRD"| ESM
    ESM -->|"emits Event"| RM
    RM -->|"invokes Reconcile()"| CM
    CM -->|"uses workflows"| DEM
    CM -->|"coordinates leader election"| LEM
    DEM -->|"CRUD secondary resources"| K8S
    LEM -->|"manages locks"| K8S

    %% Extensions Hooks
    CCS -->|"caches events"| ESM
    MMS -->|"exposes metrics"| RM

    %% Testing Interactions
    J5 -->|"spins up cluster"| TEST
    TEST -->|"executes Reconciler"| CM

    %% Documentation Build
    DOCS -->|"generates site"| ExternalSite["Netlify"]:::external

    %% External Interactions
    CM -->|"writes logs/metrics"| LOG

    %% Click Events
    click MWP "https://github.com/operator-framework/java-operator-sdk/blob/main/pom.xml"
    click MWP "https://github.com/operator-framework/java-operator-sdk/tree/main/.mvn/"
    click MWP "https://github.com/operator-framework/java-operator-sdk/tree/main/mvnw"
    click MWP "https://github.com/operator-framework/java-operator-sdk/blob/main/mvnw.cmd"
    click BOM "https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-bom/pom.xml"
    click BBP "https://github.com/operator-framework/java-operator-sdk/tree/main/bootstrapper-maven-plugin/"
    click AP "https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/main/java/io/javaoperatorsdk/operator/config/runtime/ControllerConfigurationAnnotationProcessor.java"
    click CM "https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework-core/"
    click CCS "https://github.com/operator-framework/java-operator-sdk/tree/main/caffeine-bounded-cache-support/"
    click MMS "https://github.com/operator-framework/java-operator-sdk/tree/main/micrometer-support/"
    click J5 "https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework-junit5/"
    click TEST "https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework-junit5/"
    click DOCS "https://github.com/operator-framework/java-operator-sdk/tree/main/docs/"
    click .github "https://github.com/operator-framework/java-operator-sdk/tree/main/.github/workflows/"

    %% Styles
    classDef build fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef runtime fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ext fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef testing fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef docs fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px
```
