# phonepe/solus architecture

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

- Interactive diagram: https://gitdiagram.com/phonepe/solus
- Repository: https://github.com/phonepe/solus

## Overview

Solus is a Java library for distributed, TTL-based deduplication using sharded Bloom filters. A client configures a storage context and uses SolusEngine to register a deduper, then check, add, or atomically add entities. The data-command layer derives Bloom-filter bit positions and shards entities before delegating reads and updates to the selected backend. Registration metadata and filter data are separate concerns; README capabilities also include batch operations and DC/XDC levels. Backend links reflect documented Aerospike and HBase support; unsampled CRUD and HBase data-store internals limit finer-grained wiring.

Main entry points: [`src/main/java/com/phonepe/solus/SolusEngine.java`](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/SolusEngine.java) (Solus Engine), [`src/main/java/com/phonepe/solus/commands/impl/DeDuperDataCommands.java`](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/commands/impl/DeDuperDataCommands.java) (Data Commands), [`src/main/java/com/phonepe/solus/store/IDeDuperMetaStore.java`](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperMetaStore.java) (Metadata Store API), [`src/main/java/com/phonepe/solus/store/IDeDuperDataStore.java`](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperDataStore.java) (Data Store API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Library API"]
  node_engine["Solus Engine<br/>[SolusEngine.java]"]
  node_crud["CRUD Commands"]
  node_data["Data Commands"]
end

subgraph group_logic["Deduplication Logic"]
  node_config["Deduper Config<br/>[DeDuperConfig.java]"]
  node_level["DC / XDC<br/>[DeDuperLevel.java]"]
  node_deduper["Deduper State<br/>[DeDuper.java]"]
  node_shard["Shard Calculator"]
  node_bits["Bloom Bit Positions"]
end

subgraph group_metadata["Deduper Metadata"]
  node_meta_iface["Metadata Store API"]
  node_aero_meta["Aerospike Metadata"]
  node_hbase_meta["HBase Metadata"]
end

subgraph group_storage["Storage Backends"]
  node_meta_db[("Metadata Backend")]
  node_store_iface["Data Store API"]
  node_aero_data["Aerospike Filter Data"]
  node_hbase_data["HBase Filter Data"]
  node_aero_context["Aerospike Context"]
  node_hbase_context["HBase Context"]
end

node_consumer(("Library Client"))
node_aero_db[("Aerospike")]
node_hbase_db[("HBase")]

node_consumer -->|"calls"| node_engine
node_engine -->|"registers via"| node_crud
node_engine -->|"loads deduper"| node_crud
node_engine -->|"runs operations"| node_data
node_engine -->|"accepts config"| node_config
node_crud -->|"manages metadata"| node_meta_iface
node_meta_iface -.->|"Aerospike implementation"| node_aero_meta
node_meta_iface -.->|"HBase implementation"| node_hbase_meta
node_aero_meta -->|"reads/writes"| node_meta_db
node_hbase_meta -->|"reads/writes"| node_meta_db
node_data -->|"calculates shard"| node_shard
node_data -->|"derives bit positions"| node_bits
node_data -->|"reads/updates"| node_store_iface
node_data -->|"uses configuration"| node_deduper
node_store_iface -.->|"Aerospike implementation"| node_aero_data
node_store_iface -.->|"HBase implementation"| node_hbase_data
node_aero_data -->|"reads/writes TTL bins"| node_aero_db
node_hbase_data -->|"reads/writes filter data"| node_hbase_db
node_aero_context -.->|"configures backend"| node_aero_data
node_hbase_context -.->|"configures backend"| node_hbase_data
node_deduper -->|"selects level"| node_level

click node_engine "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/SolusEngine.java"
click node_crud "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/commands/impl/DeDuperCrudCommands.java"
click node_data "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/commands/impl/DeDuperDataCommands.java"
click node_config "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/config/DeDuperConfig.java"
click node_level "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/config/DeDuperLevel.java"
click node_deduper "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/DeDuper.java"
click node_shard "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/shard/ShardCalculator.java"
click node_bits "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/filter/impl/EntityWithBitPositions.java"
click node_meta_iface "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperMetaStore.java"
click node_aero_meta "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperMetaStore.java"
click node_hbase_meta "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperMetaStore.java"
click node_store_iface "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperDataStore.java"
click node_aero_data "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperDataStore.java"
click node_hbase_data "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperDataStore.java"
click node_aero_context "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/context/impl/AerospikeStorageContext.java"
click node_hbase_context "https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/context/impl/HBaseStorageContext.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_engine,node_crud,node_data,node_consumer toneBlue
class node_config,node_level,node_deduper,node_shard,node_bits,node_aero_db,node_hbase_db toneAmber
class node_meta_iface,node_aero_meta,node_hbase_meta toneMint
class node_meta_db,node_store_iface,node_aero_data,node_hbase_data,node_aero_context,node_hbase_context toneRose
```

## Components

### Library API

- [Solus Engine](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/SolusEngine.java): `src/main/java/com/phonepe/solus/SolusEngine.java`
- [CRUD Commands](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/commands/impl/DeDuperCrudCommands.java): `src/main/java/com/phonepe/solus/commands/impl/DeDuperCrudCommands.java`
- [Data Commands](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/commands/impl/DeDuperDataCommands.java): `src/main/java/com/phonepe/solus/commands/impl/DeDuperDataCommands.java`

### Deduplication Logic

- [Deduper Config](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/config/DeDuperConfig.java): `src/main/java/com/phonepe/solus/config/DeDuperConfig.java`
- [DC / XDC](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/config/DeDuperLevel.java): `src/main/java/com/phonepe/solus/config/DeDuperLevel.java`
- [Deduper State](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/DeDuper.java): `src/main/java/com/phonepe/solus/DeDuper.java`
- [Shard Calculator](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/shard/ShardCalculator.java): `src/main/java/com/phonepe/solus/shard/ShardCalculator.java`
- [Bloom Bit Positions](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/filter/impl/EntityWithBitPositions.java): `src/main/java/com/phonepe/solus/filter/impl/EntityWithBitPositions.java`

### Deduper Metadata

- [Metadata Store API](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperMetaStore.java): `src/main/java/com/phonepe/solus/store/IDeDuperMetaStore.java`
- [Aerospike Metadata](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperMetaStore.java): `src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperMetaStore.java`
- [HBase Metadata](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperMetaStore.java): `src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperMetaStore.java`

### Storage Backends

- **Metadata Backend**
- [Data Store API](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/IDeDuperDataStore.java): `src/main/java/com/phonepe/solus/store/IDeDuperDataStore.java`
- [Aerospike Filter Data](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperDataStore.java): `src/main/java/com/phonepe/solus/store/aerospike/AerospikeDeDuperDataStore.java`
- [HBase Filter Data](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperDataStore.java): `src/main/java/com/phonepe/solus/store/hbase/HBaseDeDuperDataStore.java`
- [Aerospike Context](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/context/impl/AerospikeStorageContext.java): `src/main/java/com/phonepe/solus/store/context/impl/AerospikeStorageContext.java`
- [HBase Context](https://github.com/phonepe/solus/blob/main/src/main/java/com/phonepe/solus/store/context/impl/HBaseStorageContext.java): `src/main/java/com/phonepe/solus/store/context/impl/HBaseStorageContext.java`

### Other components

- **Library Client**
- **Aerospike**
- **HBase**

## Connections

- Library Client → Solus Engine: calls
- Solus Engine → CRUD Commands: registers via
- Solus Engine → CRUD Commands: loads deduper
- Solus Engine → Data Commands: runs operations
- Solus Engine → Deduper Config: accepts config
- CRUD Commands → Metadata Store API: manages metadata
- Metadata Store API → Aerospike Metadata: Aerospike implementation
- Metadata Store API → HBase Metadata: HBase implementation
- Aerospike Metadata → Metadata Backend: reads/writes
- HBase Metadata → Metadata Backend: reads/writes
- Data Commands → Shard Calculator: calculates shard
- Data Commands → Bloom Bit Positions: derives bit positions
- Data Commands → Data Store API: reads/updates
- Data Commands → Deduper State: uses configuration
- Data Store API → Aerospike Filter Data: Aerospike implementation
- Data Store API → HBase Filter Data: HBase implementation
- Aerospike Filter Data → Aerospike: reads/writes TTL bins
- HBase Filter Data → HBase: reads/writes filter data
- Aerospike Context → Aerospike Filter Data: configures backend
- HBase Context → HBase Filter Data: configures backend
- Deduper State → DC / XDC: selects level