# snuk87/keycloak-kafka architecture

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

- Interactive diagram: https://gitdiagram.com/snuk87/keycloak-kafka
- Repository: https://github.com/snuk87/keycloak-kafka

## Overview

##### Project Type and Purpose
- This is an open-source Keycloak SPI (Service Provider Interface) module written in Java. Its sole purpose is to capture Keycloak user/admin events and forward them to an Apache Kafka cluster.

##### High-Level Components
a. Keycloak Server Core
- Loads SPI providers from the `providers` folder (your fat-jar).
- Emits internal events (`EventListenerProvider`).
b. Keycloak Kafka Module (SPI Provider)
- `KafkaEventListenerProviderFactory` registers the provider.
- `KafkaEventListenerProvider` implements the SPI interface to receive events.
- `KafkaProducerConfig` reads environment/CLI settings.
- `KafkaProducerFactory` (and `StandardProducerFactory`) create/configure Kafka producers.
c. Kafka Cluster (External Service)
- One or more brokers listening on `bootstrapServers`.
- One or two topics: `topicEvents` and optional `topicAdminEvents`.
d. (Optional) Downstream Consumer
- E.g., a Spring Boot app using `@KafkaListener` to consume events.

##### Relationships and Data Flow
- On user/admin actions Keycloak generates an `Event` → Keycloak Core invokes `KafkaEventListenerProvider::onEvent()` → provider serializes the event → sends it via a KafkaProducer created by `KafkaProducerFactory` → Kafka Broker → optional downstream consumers.
- Configuration flows from environment variables or CLI flags into `KafkaProducerConfig`.

##### Architectural Patterns and Design Principles
- SPI/Plugin Architecture: decouples module from Keycloak core.
- Factory Pattern: `KafkaProducerFactory` hides producer instantiation.
- Configuration by Convention: environment variables / CLI flags drive both SPI and Kafka client configs.
- Single Responsibility: each class has a focused role (provider, factory, config).

##### Essential Details
- Configuration parameters (e.g., `KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_TOPIC`).
- That the module is a “fat jar” built by Maven (`pom.xml`, assembly plugin).
- Test suite side-by-side (for completeness) or omit if focusing strictly on runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ENV["Environment Variables / CLI Flags"]:::config

    subgraph "Keycloak Server vX.Y" 
        KC_CORE["Keycloak Core"]:::keycloak

        subgraph "Keycloak Kafka Module"
            SPI_REG["SPI Registration"]:::module
            FACTORYF["KafkaEventListenerProviderFactory"]:::module
            PROVIDER["KafkaEventListenerProvider"]:::module
            PRODFACT["KafkaProducerFactory"]:::module
            STDFACT["StandardProducerFactory"]:::module
            CONFIG["KafkaProducerConfig"]:::module
        end
    end

    KAFKA["Kafka Cluster"]:::external
    subgraph "Topics"
        TOPIC1["keycloak-events"]:::topic
        TOPIC2["keycloak-admin-events"]:::topic
    end

    CLIENT["Spring Boot Consumer"]:::external

    DOCKER_NET["Docker Compose Network"]:::external

    ENV -->|"provides config"| CONFIG
    KC_CORE -->|"loads SPI Provider"| SPI_REG
    SPI_REG -->|"registers factory"| FACTORYF
    FACTORYF -->|"instantiates"| PROVIDER
    PROVIDER -->|"uses factory"| PRODFACT
    PRODFACT -->|"creates producer"| STDFACT
    CONFIG -->|"configures"| PRODFACT
    PROVIDER -->|"produce()"| KAFKA
    KAFKA -->|"consume()"| CLIENT
    DOCKER_NET --- KC_CORE
    DOCKER_NET --- KAFKA

    click FACTORYF "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/java/com/github/snuk87/keycloak/kafka/KafkaEventListenerProviderFactory.java"
    click PROVIDER "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/java/com/github/snuk87/keycloak/kafka/KafkaEventListenerProvider.java"
    click CONFIG "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/java/com/github/snuk87/keycloak/kafka/KafkaProducerConfig.java"
    click PRODFACT "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/java/com/github/snuk87/keycloak/kafka/KafkaProducerFactory.java"
    click STDFACT "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/java/com/github/snuk87/keycloak/kafka/KafkaStandardProducerFactory.java"
    click SPI_REG "https://github.com/snuk87/keycloak-kafka/blob/master/src/main/resources/META-INF/services/org.keycloak.events.EventListenerProviderFactory"
    click POM "https://github.com/snuk87/keycloak-kafka/blob/master/pom.xml"
    click DOCKERF "https://github.com/snuk87/keycloak-kafka/tree/master/Dockerfile"
    click COMPOSE "https://github.com/snuk87/keycloak-kafka/blob/master/docker-compose.yml"
    click TEST1 "https://github.com/snuk87/keycloak-kafka/blob/master/src/test/java/com/github/snuk87/keycloak/kafka/KafkaEventListenerProviderTests.java"
    click TEST2 "https://github.com/snuk87/keycloak-kafka/blob/master/src/test/java/com/github/snuk87/keycloak/kafka/KafkaProducerConfigTests.java"

    classDef keycloak fill:#D6EAF8,stroke:#1B4F72
    classDef module fill:#A9DFBF,stroke:#196F3D
    classDef config fill:#ABEBC6,stroke:#1D8348
    classDef external fill:#FAD7A0,stroke:#B9770E
    classDef topic fill:#F5CBA7,stroke:#BA4A00
```
