# georgeslks/java_lowlatency_eventmessaging_engine architecture

> Architecture diagram of the GitHub repository georgeslks/java_lowlatency_eventmessaging_engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgeslks/java_lowlatency_eventmessaging_engine
- Repository: https://github.com/georgeslks/java_lowlatency_eventmessaging_engine

## Overview

This Java low-latency event messaging engine accepts framed events over TCP, decodes them, queues them through a bounded ring buffer, and persists them to ClickHouse over HTTP. Main wires the runtime; client handlers own decoding and publication, while the consumer owns dequeueing and processing. Configuration comes from environment variables. The README documents the broker and ring-buffer/network pipeline; unsampled internals are represented only where the source index or documentation supports them.

Main entry points: [`src/main/java/engine/Main.java`](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Main.java) (Engine Main), [`src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java`](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java) (HTTP Writer), [`src/main/java/engine/Partition.java`](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Partition.java) (Partition), [`src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java`](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java) (ClickHouse Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["TCP Ingress"]
  node_network_server["Network Server<br/>[NetworkServer.java]"]
  node_client_handler["Client Handler<br/>[ClientHandler.java]"]
  node_event_decoder["Event Decoder<br/>[EventDecoder.java]"]
  node_event_type["Event Type<br/>[EventType.java]"]
end

subgraph group_queueing["Event Queue"]
  node_event["Event Model<br/>[Event.java]"]
  node_event_bus["Event Bus<br/>[EventBus.java]"]
  node_partition["Partition<br/>[Partition.java]"]
  node_ring_buffer["Ring Buffer<br/>[RingBuffer.java]"]
  node_event_consumer["Event Consumer<br/>[EventConsumer.java]"]
end

subgraph group_persistence["ClickHouse Persistence"]
  node_event_processor["Event Processor"]
  node_clickhouse_writer["HTTP Writer"]
  node_http_client["HTTP Client"]
  node_clickhouse_config["ClickHouse Config"]
end

subgraph group_runtime["Runtime Setup"]
  node_main["Engine Main<br/>[Main.java]"]
end

node_tcp_clients(("TCP Clients"))
node_clickhouse[("ClickHouse")]
node_environment(("Environment"))

node_tcp_clients -->|"opens TCP"| node_network_server
node_network_server -->|"dispatches clients"| node_client_handler
node_client_handler -->|"decodes payload"| node_event_decoder
node_event_decoder -->|"creates events"| node_event
node_event_decoder -->|"uses event types"| node_event_type
node_event -->|"has type"| node_event_type
node_client_handler -->|"publishes events"| node_event_bus
node_event_bus -->|"publishes to"| node_partition
node_partition -->|"adds and polls"| node_ring_buffer
node_event_consumer -->|"consumes from"| node_partition
node_event_consumer -->|"processes event"| node_event_processor
node_event_processor -->|"writes event"| node_clickhouse_writer
node_clickhouse_writer -->|"sends insert"| node_http_client
node_clickhouse_writer -->|"reads settings"| node_clickhouse_config
node_http_client -->|"builds endpoint"| node_clickhouse_config
node_clickhouse_writer -->|"inserts over HTTP"| node_clickhouse
node_environment -->|"provides settings"| node_clickhouse_config
node_main -->|"initializes"| node_clickhouse_config
node_main -->|"initializes"| node_http_client
node_main -->|"initializes"| node_clickhouse_writer
node_main -->|"initializes"| node_ring_buffer
node_main -->|"initializes"| node_partition
node_main -->|"initializes"| node_event_bus
node_main -->|"initializes"| node_event_processor
node_main -->|"starts consumer"| node_event_consumer
node_main -->|"starts server"| node_network_server

click node_network_server "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/NetworkServer.java"
click node_client_handler "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/ClientHandler.java"
click node_event_decoder "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/EventDecoder.java"
click node_event_type "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventType.java"
click node_event "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Event.java"
click node_event_bus "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventBus.java"
click node_partition "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Partition.java"
click node_ring_buffer "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/RingBuffer.java"
click node_event_consumer "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventConsumer.java"
click node_event_processor "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventProcessor.java"
click node_clickhouse_writer "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java"
click node_http_client "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpClient.java"
click node_clickhouse_config "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java"
click node_main "https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Main.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_network_server,node_client_handler,node_event_decoder,node_event_type,node_tcp_clients toneBlue
class node_event,node_event_bus,node_partition,node_ring_buffer,node_event_consumer,node_clickhouse toneAmber
class node_event_processor,node_clickhouse_writer,node_http_client,node_clickhouse_config toneMint
class node_main toneRose
class node_environment toneIndigo
```

## Components

### TCP Ingress

- [Network Server](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/NetworkServer.java): `src/main/java/engine/network/NetworkServer.java`
- [Client Handler](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/ClientHandler.java): `src/main/java/engine/network/ClientHandler.java`
- [Event Decoder](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/network/EventDecoder.java): `src/main/java/engine/network/EventDecoder.java`
- [Event Type](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventType.java): `src/main/java/engine/EventType.java`

### Event Queue

- [Event Model](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Event.java): `src/main/java/engine/Event.java`
- [Event Bus](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventBus.java): `src/main/java/engine/EventBus.java`
- [Partition](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Partition.java): `src/main/java/engine/Partition.java`
- [Ring Buffer](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/RingBuffer.java): `src/main/java/engine/RingBuffer.java`
- [Event Consumer](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventConsumer.java): `src/main/java/engine/EventConsumer.java`

### ClickHouse Persistence

- [Event Processor](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/EventProcessor.java): `src/main/java/engine/EventProcessor.java`
- [HTTP Writer](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java): `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java`
- [HTTP Client](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpClient.java): `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpClient.java`
- [ClickHouse Config](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java): `src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java`

### Runtime Setup

- [Engine Main](https://github.com/georgeslks/java_lowlatency_eventmessaging_engine/blob/main/src/main/java/engine/Main.java): `src/main/java/engine/Main.java`

### Other components

- **TCP Clients**
- **ClickHouse**
- **Environment**

## Connections

- TCP Clients → Network Server: opens TCP (evidence: `src/main/java/engine/network/NetworkServer.java`)
- Network Server → Client Handler: dispatches clients (evidence: `src/main/java/engine/network/NetworkServer.java`)
- Client Handler → Event Decoder: decodes payload (evidence: `src/main/java/engine/network/ClientHandler.java`)
- Event Decoder → Event Model: creates events (evidence: `src/main/java/engine/network/EventDecoder.java`)
- Event Decoder → Event Type: uses event types (evidence: `src/main/java/engine/network/EventDecoder.java`)
- Event Model → Event Type: has type (evidence: `src/main/java/engine/Event.java`)
- Client Handler → Event Bus: publishes events (evidence: `src/main/java/engine/network/ClientHandler.java`)
- Event Bus → Partition: publishes to (evidence: `src/main/java/engine/EventBus.java`)
- Partition → Ring Buffer: adds and polls (evidence: `src/main/java/engine/Partition.java`)
- Event Consumer → Partition: consumes from (evidence: `src/main/java/engine/EventConsumer.java`)
- Event Consumer → Event Processor: processes event (evidence: `src/main/java/engine/EventConsumer.java`)
- Event Processor → HTTP Writer: writes event (evidence: `src/main/java/engine/EventProcessor.java`)
- HTTP Writer → HTTP Client: sends insert (evidence: `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java`)
- HTTP Writer → ClickHouse Config: reads settings (evidence: `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java`)
- HTTP Client → ClickHouse Config: builds endpoint (evidence: `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpClient.java`)
- HTTP Writer → ClickHouse: inserts over HTTP (evidence: `src/main/java/engine/clickhouseConnectors/http/ClickHouseHttpWriter.java`)
- Environment → ClickHouse Config: provides settings (evidence: `src/main/java/engine/clickhouseConnectors/config/ClickHouseConfig.java`)
- Engine Main → ClickHouse Config: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → HTTP Client: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → HTTP Writer: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Ring Buffer: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Partition: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Event Bus: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Event Processor: initializes (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Event Consumer: starts consumer (evidence: `src/main/java/engine/Main.java`)
- Engine Main → Network Server: starts server (evidence: `src/main/java/engine/Main.java`)
