# dhruv0306/eventbus architecture

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

- Interactive diagram: https://gitdiagram.com/dhruv0306/eventbus
- Repository: https://github.com/dhruv0306/eventbus

## Overview

This is a Java library for thread-safe, in-memory event publication and subscription. An application registers typed, optionally filtered handlers, then publishes synchronously on its calling thread or asynchronously on virtual threads; the bus limits concurrent async handler execution and routes missing-subscriber or handler failures to a bounded dead-letter queue. The README also documents extensible event types and configurable limits. The implementation and queue behavior are supported by sampled source; other documented capabilities are represented at the public API level.

Main entry points: [`src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java`](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java) (Concurrent event bus), [`src/main/java/io/github/dhruv0306/eventbus/DeadLetterQueue.java`](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/DeadLetterQueue.java) (Dead-letter API), [`src/main/java/io/github/dhruv0306/eventbus/BoundedDeadLetterQueue.java`](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/BoundedDeadLetterQueue.java) (Bounded dead-letter queue), [`src/main/java/io/github/dhruv0306/eventbus/EventBus.java`](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventBus.java) (EventBus API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_event["Custom event<br/>[Event.java]"]
  node_bus_api["EventBus API<br/>[EventBus.java]"]
  node_subscription["Subscription handle<br/>[Subscription.java]"]
  node_config["Bus configuration"]
end

subgraph group_dispatch["Event dispatch"]
  node_concurrent_bus["Concurrent event bus"]
  node_async_executor["Virtual-thread executor"]
  node_throttle["Dispatch semaphore"]
end

subgraph group_reliability["Failure handling"]
  node_dlq_api["Dead-letter API"]
  node_bounded_dlq["Bounded dead-letter queue"]
  node_dropped_error["Dropped-event exception"]
end

node_application(("Application"))
node_handler(("Subscriber handlers"))

node_application -->|"subscribes and publishes"| node_bus_api
node_concurrent_bus -->|"implements"| node_bus_api
node_application -->|"defines"| node_event
node_concurrent_bus -->|"reads limits"| node_config
node_concurrent_bus -->|"returns handle"| node_subscription
node_concurrent_bus -->|"dispatches events"| node_handler
node_concurrent_bus -->|"submits async tasks"| node_async_executor
node_async_executor -->|"acquires permits"| node_throttle
node_async_executor -->|"runs async handler"| node_handler
node_concurrent_bus -->|"runs sync handler"| node_handler
node_concurrent_bus -->|"offers failures"| node_dlq_api
node_concurrent_bus -->|"creates queue"| node_bounded_dlq
node_bounded_dlq -->|"implements"| node_dlq_api
node_application -->|"drains letters"| node_dlq_api
node_concurrent_bus -->|"throws on overflow"| node_dropped_error

click node_event "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/Event.java"
click node_bus_api "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventBus.java"
click node_subscription "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/Subscription.java"
click node_config "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventBusConfig.java"
click node_concurrent_bus "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java"
click node_async_executor "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java"
click node_throttle "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java"
click node_dlq_api "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/DeadLetterQueue.java"
click node_bounded_dlq "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/BoundedDeadLetterQueue.java"
click node_dropped_error "https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventDroppedException.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_event,node_bus_api,node_subscription,node_config toneBlue
class node_concurrent_bus,node_async_executor,node_throttle toneAmber
class node_dlq_api,node_bounded_dlq,node_dropped_error,node_handler toneMint
class node_application toneIndigo
```

## Components

### Public API

- [Custom event](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/Event.java): `src/main/java/io/github/dhruv0306/eventbus/Event.java`
- [EventBus API](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventBus.java): `src/main/java/io/github/dhruv0306/eventbus/EventBus.java`
- [Subscription handle](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/Subscription.java): `src/main/java/io/github/dhruv0306/eventbus/Subscription.java`
- [Bus configuration](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventBusConfig.java): `src/main/java/io/github/dhruv0306/eventbus/EventBusConfig.java`

### Event dispatch

- [Concurrent event bus](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java): `src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java`
- [Virtual-thread executor](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java): `src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java`
- [Dispatch semaphore](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java): `src/main/java/io/github/dhruv0306/eventbus/ConcurrentEventBus.java`

### Failure handling

- [Dead-letter API](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/DeadLetterQueue.java): `src/main/java/io/github/dhruv0306/eventbus/DeadLetterQueue.java`
- [Bounded dead-letter queue](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/BoundedDeadLetterQueue.java): `src/main/java/io/github/dhruv0306/eventbus/BoundedDeadLetterQueue.java`
- [Dropped-event exception](https://github.com/dhruv0306/eventbus/blob/main/src/main/java/io/github/dhruv0306/eventbus/EventDroppedException.java): `src/main/java/io/github/dhruv0306/eventbus/EventDroppedException.java`

### Other components

- **Application**
- **Subscriber handlers**

## Connections

- Application → EventBus API: subscribes and publishes
- Concurrent event bus → EventBus API: implements
- Application → Custom event: defines
- Concurrent event bus → Bus configuration: reads limits
- Concurrent event bus → Subscription handle: returns handle
- Concurrent event bus → Subscriber handlers: dispatches events
- Concurrent event bus → Virtual-thread executor: submits async tasks
- Virtual-thread executor → Dispatch semaphore: acquires permits
- Virtual-thread executor → Subscriber handlers: runs async handler
- Concurrent event bus → Subscriber handlers: runs sync handler
- Concurrent event bus → Dead-letter API: offers failures
- Concurrent event bus → Bounded dead-letter queue: creates queue
- Bounded dead-letter queue → Dead-letter API: implements
- Application → Dead-letter API: drains letters
- Concurrent event bus → Dropped-event exception: throws on overflow