# shreyshringare/conduit architecture

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

- Interactive diagram: https://gitdiagram.com/shreyshringare/conduit
- Repository: https://github.com/shreyshringare/conduit

## Overview

Conduit provides a TCP message broker with producer/consumer clients, durable partition logs, group offsets, topic management, rate limiting, metrics, and a RingWatch fraud-ring stream processor. The same repository also contains MerchantRisk, whose API-facing engine evaluates configured rules and velocity limits with per-merchant circuit breaking and optional event publishing. Edges reflect README descriptions or visible call/reference evidence; unsampled connections are omitted rather than inferred.

Main entry points: [`conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java) (Request handler), [`merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java) (Risk engine), [`conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`](https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java) (RingWatch consumer), [`conduit-core/src/main/java/dev/conduit/log/PartitionLog.java`](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/PartitionLog.java) (Partition log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Broker clients"]
  node_producer["Producer"]
  node_consumer["Consumer"]
end

subgraph group_broker["Broker runtime"]
  node_wire["Wire codec<br/>[FrameDecoder.java]"]
  node_handler["Request handler"]
  node_broker_server["Broker server<br/>[Broker.java]"]
  node_ratelimit["Connection rate limits"]
  node_metrics["Broker metrics<br/>[BrokerMetrics.java]"]
end

subgraph group_storage["Log and offsets"]
  node_topics["Topics and partitions<br/>[TopicManager.java]"]
  node_partition_log[("Partition log<br/>[PartitionLog.java]")]
  node_segment[("Mapped segments<br/>[SegmentFile.java]")]
  node_index["Sparse offset index"]
  node_retention["Log retention"]
  node_offsets[("Consumer offsets<br/>[OffsetStore.java]")]
end

subgraph group_ringwatch["RingWatch detection"]
  node_ring_consumer["RingWatch consumer"]
  node_graph["Incremental graph"]
  node_scc["Sliding-window SCC"]
  node_fraud_ring["Fraud ring event"]
end

subgraph group_risk["MerchantRisk engine"]
  node_risk_api["Risk API model"]
  node_risk_engine["Risk engine"]
  node_rule_loader["Rule loader<br/>[RuleLoader.java]"]
  node_evaluator["Rule evaluator<br/>[RuleEvaluator.java]"]
  node_velocity["Velocity checker"]
  node_breaker["Merchant circuit breaker"]
  node_publisher["Risk event publisher"]
end

node_producer_actor(("Producer application"))
node_consumer_actor(("Consumer application"))
node_risk_actor(("Risk API caller"))

node_producer_actor -->|"sends messages"| node_producer
node_producer -->|"encodes requests"| node_wire
node_consumer_actor -->|"polls records"| node_consumer
node_consumer -->|"encodes requests"| node_wire
node_broker_server -->|"dispatches connections"| node_handler
node_handler -->|"decodes frames"| node_wire
node_handler -->|"resolves partitions"| node_topics
node_handler -->|"checks produce limits"| node_ratelimit
node_handler -->|"stores offsets"| node_offsets
node_handler -->|"records metrics"| node_metrics
node_topics -->|"creates and returns"| node_partition_log
node_partition_log -->|"appends and reads"| node_segment
node_partition_log -->|"indexes offsets"| node_index
node_retention -->|"manages retention"| node_partition_log
node_handler -->|"appends or fetches"| node_partition_log
node_consumer -->|"requests fetch and commit"| node_handler
node_risk_actor -->|"evaluates transaction"| node_risk_engine
node_risk_engine -->|"builds context"| node_risk_api
node_risk_engine -->|"loads configured rules"| node_rule_loader
node_risk_engine -->|"evaluates rules"| node_evaluator
node_rule_loader -.->|"provides rule definitions"| node_evaluator
node_risk_engine -->|"checks velocity"| node_velocity
node_risk_engine -->|"checks and records outcomes"| node_breaker
node_risk_engine -->|"publishes decisions"| node_publisher
node_breaker -->|"publishes circuit events"| node_publisher
node_publisher -->|"publishes via client"| node_producer
node_ring_consumer -->|"consumes transactions"| node_consumer
node_ring_consumer -->|"adds transaction edges"| node_graph
node_scc -->|"analyzes graph"| node_graph
node_ring_consumer -->|"detects cycles"| node_scc
node_ring_consumer -->|"creates alert event"| node_fraud_ring
node_ring_consumer -->|"publishes alert and DLQ"| node_producer

click node_producer "https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/client/ConduitProducer.java"
click node_consumer "https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/client/ConduitConsumer.java"
click node_wire "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/protocol/FrameDecoder.java"
click node_handler "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java"
click node_broker_server "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/broker/Broker.java"
click node_topics "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/topic/TopicManager.java"
click node_partition_log "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/PartitionLog.java"
click node_segment "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/SegmentFile.java"
click node_index "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/SparseOffsetIndex.java"
click node_retention "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/LogRetentionManager.java"
click node_offsets "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/consumer/OffsetStore.java"
click node_ratelimit "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ratelimit/ConnectionRateLimits.java"
click node_metrics "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/metrics/BrokerMetrics.java"
click node_ring_consumer "https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java"
click node_graph "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/IncrementalGraph.java"
click node_scc "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/SlidingWindowSCC.java"
click node_fraud_ring "https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/FraudRingDetectedEvent.java"
click node_risk_api "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/api/TransactionContext.java"
click node_risk_engine "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java"
click node_rule_loader "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleLoader.java"
click node_evaluator "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleEvaluator.java"
click node_velocity "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/velocity/SlidingWindowVelocityChecker.java"
click node_breaker "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/circuit/MerchantCircuitBreaker.java"
click node_publisher "https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/event/RiskEventPublisher.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_producer,node_consumer toneBlue
class node_wire,node_handler,node_broker_server,node_ratelimit,node_metrics toneAmber
class node_topics,node_partition_log,node_segment,node_index,node_retention,node_offsets,node_risk_actor toneMint
class node_ring_consumer,node_graph,node_scc,node_fraud_ring toneRose
class node_risk_api,node_risk_engine,node_rule_loader,node_evaluator,node_velocity,node_breaker,node_publisher,node_producer_actor,node_consumer_actor toneIndigo
```

## Components

### Broker clients

- [Producer](https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/client/ConduitProducer.java): `conduit-client/src/main/java/dev/conduit/client/ConduitProducer.java`
- [Consumer](https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/client/ConduitConsumer.java): `conduit-client/src/main/java/dev/conduit/client/ConduitConsumer.java`

### Broker runtime

- [Wire codec](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/protocol/FrameDecoder.java): `conduit-core/src/main/java/dev/conduit/protocol/FrameDecoder.java`
- [Request handler](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java): `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`
- [Broker server](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/broker/Broker.java): `conduit-core/src/main/java/dev/conduit/broker/Broker.java`
- [Connection rate limits](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ratelimit/ConnectionRateLimits.java): `conduit-core/src/main/java/dev/conduit/ratelimit/ConnectionRateLimits.java`
- [Broker metrics](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/metrics/BrokerMetrics.java): `conduit-core/src/main/java/dev/conduit/metrics/BrokerMetrics.java`

### Log and offsets

- [Topics and partitions](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/topic/TopicManager.java): `conduit-core/src/main/java/dev/conduit/topic/TopicManager.java`
- [Partition log](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/PartitionLog.java): `conduit-core/src/main/java/dev/conduit/log/PartitionLog.java`
- [Mapped segments](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/SegmentFile.java): `conduit-core/src/main/java/dev/conduit/log/SegmentFile.java`
- [Sparse offset index](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/SparseOffsetIndex.java): `conduit-core/src/main/java/dev/conduit/log/SparseOffsetIndex.java`
- [Log retention](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/log/LogRetentionManager.java): `conduit-core/src/main/java/dev/conduit/log/LogRetentionManager.java`
- [Consumer offsets](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/consumer/OffsetStore.java): `conduit-core/src/main/java/dev/conduit/consumer/OffsetStore.java`

### RingWatch detection

- [RingWatch consumer](https://github.com/shreyshringare/conduit/blob/master/conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java): `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`
- [Incremental graph](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/IncrementalGraph.java): `conduit-core/src/main/java/dev/conduit/ringwatch/IncrementalGraph.java`
- [Sliding-window SCC](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/SlidingWindowSCC.java): `conduit-core/src/main/java/dev/conduit/ringwatch/SlidingWindowSCC.java`
- [Fraud ring event](https://github.com/shreyshringare/conduit/blob/master/conduit-core/src/main/java/dev/conduit/ringwatch/FraudRingDetectedEvent.java): `conduit-core/src/main/java/dev/conduit/ringwatch/FraudRingDetectedEvent.java`

### MerchantRisk engine

- [Risk API model](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/api/TransactionContext.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/api/TransactionContext.java`
- [Risk engine](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`
- [Rule loader](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleLoader.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleLoader.java`
- [Rule evaluator](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleEvaluator.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/rules/RuleEvaluator.java`
- [Velocity checker](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/velocity/SlidingWindowVelocityChecker.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/velocity/SlidingWindowVelocityChecker.java`
- [Merchant circuit breaker](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/circuit/MerchantCircuitBreaker.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/circuit/MerchantCircuitBreaker.java`
- [Risk event publisher](https://github.com/shreyshringare/conduit/blob/master/merchantrisk-core/src/main/java/dev/conduit/merchantrisk/event/RiskEventPublisher.java): `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/event/RiskEventPublisher.java`

### Other components

- **Producer application**
- **Consumer application**
- **Risk API caller**

## Connections

- Producer application → Producer: sends messages
- Producer → Wire codec: encodes requests (evidence: `conduit-client/src/main/java/dev/conduit/client/ConduitProducer.java`)
- Consumer application → Consumer: polls records
- Consumer → Wire codec: encodes requests (evidence: `conduit-client/src/main/java/dev/conduit/client/ConduitConsumer.java`)
- Broker server → Request handler: dispatches connections (evidence: `conduit-core/src/main/java/dev/conduit/broker/Broker.java`)
- Request handler → Wire codec: decodes frames (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Request handler → Topics and partitions: resolves partitions (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Request handler → Connection rate limits: checks produce limits (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Request handler → Consumer offsets: stores offsets (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Request handler → Broker metrics: records metrics (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Topics and partitions → Partition log: creates and returns (evidence: `conduit-core/src/main/java/dev/conduit/topic/TopicManager.java`)
- Partition log → Mapped segments: appends and reads (evidence: `conduit-core/src/main/java/dev/conduit/log/PartitionLog.java`)
- Partition log → Sparse offset index: indexes offsets
- Log retention → Partition log: manages retention (evidence: `conduit-core/src/main/java/dev/conduit/log/LogRetentionManager.java`)
- Request handler → Partition log: appends or fetches (evidence: `conduit-core/src/main/java/dev/conduit/broker/BrokerConnectionHandler.java`)
- Consumer → Request handler: requests fetch and commit
- Risk API caller → Risk engine: evaluates transaction
- Risk engine → Risk API model: builds context (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Risk engine → Rule loader: loads configured rules (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Risk engine → Rule evaluator: evaluates rules (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Rule loader → Rule evaluator: provides rule definitions
- Risk engine → Velocity checker: checks velocity (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Risk engine → Merchant circuit breaker: checks and records outcomes (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Risk engine → Risk event publisher: publishes decisions (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/MerchantRiskEngine.java`)
- Merchant circuit breaker → Risk event publisher: publishes circuit events (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/circuit/MerchantCircuitBreaker.java`)
- Risk event publisher → Producer: publishes via client (evidence: `merchantrisk-core/src/main/java/dev/conduit/merchantrisk/event/RiskEventPublisher.java`)
- RingWatch consumer → Consumer: consumes transactions (evidence: `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`)
- RingWatch consumer → Incremental graph: adds transaction edges (evidence: `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`)
- Sliding-window SCC → Incremental graph: analyzes graph (evidence: `conduit-core/src/main/java/dev/conduit/ringwatch/SlidingWindowSCC.java`)
- RingWatch consumer → Sliding-window SCC: detects cycles (evidence: `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`)
- RingWatch consumer → Fraud ring event: creates alert event (evidence: `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`)
- RingWatch consumer → Producer: publishes alert and DLQ (evidence: `conduit-client/src/main/java/dev/conduit/ringwatch/RingWatchConsumer.java`)
