# srilakshmikanthanp/replica architecture

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

- Interactive diagram: https://gitdiagram.com/srilakshmikanthanp/replica
- Repository: https://github.com/srilakshmikanthanp/replica

## Overview

Replica is a Java database-replication library, with a runnable master/slave playground and web UI. A source-side write is committed with an outbox event; publishers deliver events to destination inboxes, where processing applies them in order with at-least-once delivery. Adding a station also schedules backfill of existing data. The graph includes the documented event, station, and backfill capabilities plus the playground’s domain-write path. Some core internals and UI/API wiring were not sampled, so those links rely on README statements or are omitted.

Main entry points: [`replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox`](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox) (Transactional outbox), [`replica-core/src/main/java/com/srilakshmikanthanp/replica/inbox`](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/inbox) (Inbox processing), [`replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring`](https://github.com/srilakshmikanthanp/replica/tree/master/replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring) (Spring JPA adapters), [`replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java`](https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java) (Product writes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Replication core"]
  node_outbox[("Transactional outbox")]
  node_publisher["Outbox publisher"]
  node_inbox[("Inbox processing")]
  node_events["Event registry and handlers"]
  node_backfill["Backfill jobs"]
  node_crypto["Payload cryptography"]
  node_transactions["Transaction coordination"]
end

subgraph group_api["Playground API"]
  node_write["Product writes"]
  node_domain[("Product data")]
  node_repowrite["Replication-aware writes"]
  node_wire["Replication transport"]
  node_receive["Inbox receiver"]
  node_stations["Station management"]
  node_categories["Category replication"]
  node_tags["Tag replication"]
  node_operations["Inbox/outbox views"]
  node_playgrounddata[("Playground master and slaves")]
end

subgraph group_web["Playground web"]
  node_webapp["Playground UI"]
  node_webapi["Web API client"]
end

subgraph group_persistence["Persistence adapters"]
  node_jpa["Spring JPA adapters"]
end

node_user(("Operator"))

node_user -->|"operates"| node_webapp
node_webapp -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_write
node_write -->|"reads data"| node_domain
node_write -->|"writes through"| node_repowrite
node_repowrite -.->|"records events"| node_outbox
node_publisher -.->|"sends batches"| node_wire
node_wire -.->|"delivers batch"| node_receive
node_receive -->|"stores messages"| node_inbox
node_inbox -.->|"dispatches events"| node_events
node_stations -->|"creates job"| node_backfill
node_stations -->|"registers peer"| node_playgrounddata
node_backfill -.->|"backfills data"| node_outbox
node_jpa -.->|"persists outbox"| node_outbox
node_jpa -.->|"persists inbox"| node_inbox
node_jpa -.->|"persists stations"| node_stations
node_categories -.->|"emits changes"| node_outbox
node_tags -.->|"emits changes"| node_outbox
node_operations -.->|"exposes status"| node_webapp
node_outbox -->|"delivers at least once"| node_inbox

click node_webapp "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-web/src"
click node_webapi "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-web/src/api"
click node_write "https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java"
click node_domain "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product"
click node_repowrite "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/replication"
click node_outbox "https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox"
click node_publisher "https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox"
click node_wire "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/wire"
click node_receive "https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/inbox/ReceiveController.java"
click node_inbox "https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/inbox"
click node_events "https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/event"
click node_stations "https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/station/StationService.java"
click node_backfill "https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox/backfill"
click node_crypto "https://github.com/srilakshmikanthanp/replica/blob/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/crypto/PayloadCryptography.java"
click node_transactions "https://github.com/srilakshmikanthanp/replica/blob/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/database/transaction/TransactionExecutor.java"
click node_jpa "https://github.com/srilakshmikanthanp/replica/tree/master/replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring"
click node_categories "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/category/replication"
click node_tags "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/tag/replication"
click node_operations "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication"
click node_playgrounddata "https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication"

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_outbox,node_publisher,node_inbox,node_events,node_backfill,node_crypto,node_transactions toneBlue
class node_write,node_domain,node_repowrite,node_wire,node_receive,node_stations,node_categories,node_tags,node_operations,node_playgrounddata toneAmber
class node_webapp,node_webapi toneMint
class node_jpa toneRose
class node_user toneIndigo
```

## Components

### Replication core

- [Transactional outbox](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox): `replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox`
- [Outbox publisher](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox): `replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox`
- [Inbox processing](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/inbox): `replica-core/src/main/java/com/srilakshmikanthanp/replica/inbox`
- [Event registry and handlers](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/event): `replica-core/src/main/java/com/srilakshmikanthanp/replica/event`
- [Backfill jobs](https://github.com/srilakshmikanthanp/replica/tree/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox/backfill): `replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox/backfill`
- [Payload cryptography](https://github.com/srilakshmikanthanp/replica/blob/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/crypto/PayloadCryptography.java): `replica-core/src/main/java/com/srilakshmikanthanp/replica/crypto/PayloadCryptography.java`
- [Transaction coordination](https://github.com/srilakshmikanthanp/replica/blob/master/replica-core/src/main/java/com/srilakshmikanthanp/replica/database/transaction/TransactionExecutor.java): `replica-core/src/main/java/com/srilakshmikanthanp/replica/database/transaction/TransactionExecutor.java`

### Playground API

- [Product writes](https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java`
- [Product data](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product`
- [Replication-aware writes](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/replication): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/replication`
- [Replication transport](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/wire): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/wire`
- [Inbox receiver](https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/inbox/ReceiveController.java): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/inbox/ReceiveController.java`
- [Station management](https://github.com/srilakshmikanthanp/replica/blob/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/station/StationService.java): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/station/StationService.java`
- [Category replication](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/category/replication): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/category/replication`
- [Tag replication](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/tag/replication): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/tag/replication`
- [Inbox/outbox views](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication`
- [Playground master and slaves](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication): `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication`

### Playground web

- [Playground UI](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-web/src): `replica-playground-web/src`
- [Web API client](https://github.com/srilakshmikanthanp/replica/tree/master/replica-playground-web/src/api): `replica-playground-web/src/api`

### Persistence adapters

- [Spring JPA adapters](https://github.com/srilakshmikanthanp/replica/tree/master/replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring): `replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring`

### Other components

- **Operator**

## Connections

- Operator → Playground UI: operates (evidence: `README.md`)
- Playground UI → Web API client: requests data
- Web API client → Product writes: calls API
- Product writes → Product data: reads data (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java`)
- Product writes → Replication-aware writes: writes through (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/product/controller/ProductWriteController.java`)
- Replication-aware writes → Transactional outbox: records events
- Outbox publisher → Replication transport: sends batches
- Replication transport → Inbox receiver: delivers batch (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/inbox/ReceiveController.java`)
- Inbox receiver → Inbox processing: stores messages (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/inbox/ReceiveController.java`)
- Inbox processing → Event registry and handlers: dispatches events
- Station management → Backfill jobs: creates job (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/station/StationService.java`)
- Station management → Playground master and slaves: registers peer (evidence: `replica-playground-api/src/main/java/com/srilakshmikanthanp/replica/playground/replication/station/StationService.java`)
- Backfill jobs → Transactional outbox: backfills data (evidence: `replica-core/src/main/java/com/srilakshmikanthanp/replica/outbox/backfill/BackfillJobService.java`)
- Spring JPA adapters → Transactional outbox: persists outbox (evidence: `replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring/outbox/OutboxSpringRepository.java`)
- Spring JPA adapters → Inbox processing: persists inbox (evidence: `replica-spring-jpa/src/main/java/com/srilakshmikanthanp/replica/spring/inbox/InboxSpringRepository.java`)
- Spring JPA adapters → Station management: persists stations
- Category replication → Transactional outbox: emits changes
- Tag replication → Transactional outbox: emits changes
- Inbox/outbox views → Playground UI: exposes status
- Transactional outbox → Inbox processing: delivers at least once (evidence: `README.md`)
