# gongled/kafka-workshop architecture

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

- Interactive diagram: https://gitdiagram.com/gongled/kafka-workshop
- Repository: https://github.com/gongled/kafka-workshop

## Overview

##### Project type and purpose
- This is an educational/training repository that sets up a local Kafka cluster and observability stack via Docker Compose, accompanied by slides, guides, cheatsheets, and code examples (Go producers/consumers).
- Its goal is to let users spin up a Kafka environment, produce and consume messages, and observe metrics in Grafana within 90 minutes.

##### File structure
- Top-level:
- Dockerfiles (app, kafka) for building images
- docker-compose.yml to orchestrate services
- configs for Prometheus, JMX exporter, Grafana dashboards
- docs/ with theory slides, speaker notes, guides, cheatsheets
- examples/consumer and examples/producer in Go
- Observability:
- jmx-exporter/kafka.yml
- prometheus/prometheus.yml
- grafana/provisioning and dashboards
- No application source code per se, only infrastructure and examples.

##### README for additional insights
- Two phases: Theory (slides, notes) and Practice (spin up Docker Compose, create topics, run producer/consumer, explore metrics).
- Walk-through guides and cheatsheets point to the key operational steps.

##### Detail
- Every container and config artifact that affects runtime.
- Ports exposed, e.g., 9092 for Kafka, 9464 for JMX Exporter, 9090 for Prometheus, 3000 for Grafana.
- Environment variables from .env.example that drive broker configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration and Orchestration
    ENV[".env.example"]:::config
    COMPOSE["docker-compose.yml"]:::config

    %% Docker Network Boundary
    subgraph "Docker Network" 
        style DockerNetwork stroke-dasharray: 5 5
        direction TB
        ZK["zookeeper:2181"]:::messaging
        KAFKA["kafka:9092"]:::messaging
        TOPICS[(Topics)]:::storage
        JMX["jmx-exporter:9464"]:::observability
        PROM["prometheus:9090"]:::observability
        GRAF["grafana:3000"]:::observability
    end

    %% Client Examples
    PROD["Go Producer"]:::clients
    CONS["Go Consumer"]:::clients

    %% Documentation
    DOCS["docs/"]:::docs

    %% Relationships
    ENV -->|"env vars"| COMPOSE
    COMPOSE -->|"orchestrates"| ZK
    COMPOSE --> KAFKA
    COMPOSE --> JMX
    COMPOSE --> PROM
    COMPOSE --> GRAF

    ZK ---|"register"| KAFKA
    KAFKA --> TOPICS
    PROD -->|"produce"| KAFKA
    CONS -->|"consume"| KAFKA

    KAFKA -->|"expose JMX"| JMX
    JMX -->|"metrics scrape"| PROM
    PROM -->|"query data"| GRAF

    %% Click Events
    click COMPOSE "https://github.com/gongled/kafka-workshop/blob/master/docker-compose.yml"
    click ENV "https://github.com/gongled/kafka-workshop/blob/master/.env.example"
    click ZK "https://github.com/gongled/kafka-workshop/blob/master/Dockerfile.kafka"
    click KAFKA "https://github.com/gongled/kafka-workshop/blob/master/Dockerfile.kafka"
    click JMX "https://github.com/gongled/kafka-workshop/blob/master/jmx-exporter/kafka.yml"
    click PROM "https://github.com/gongled/kafka-workshop/blob/master/prometheus/prometheus.yml"
    click GRAF "https://github.com/gongled/kafka-workshop/blob/master/grafana/provisioning/dashboards/default.yaml"
    click PROD "https://github.com/gongled/kafka-workshop/blob/master/examples/producer/main.go"
    click CONS "https://github.com/gongled/kafka-workshop/blob/master/examples/consumer/main.go"
    click DOCS "https://github.com/gongled/kafka-workshop/tree/master/docs/guide"

    %% Styles
    classDef messaging fill:#cce5ff,stroke:#4a90e2,color:#004085
    classDef observability fill:#d4edda,stroke:#28a745,color:#155724
    classDef clients fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef config fill:#f8d7da,stroke:#dc3545,color:#721c24
    classDef docs fill:#f1f1f1,stroke:#6c757d,color:#343a40

    %% Subgraph styling hack
    class DockerNetwork internalNode

    classDef internalNode stroke:#aaaaaa,stroke-dasharray:5 5,color:#333333
```
