# phonepe/dlm architecture

> Architecture diagram of the GitHub repository phonepe/dlm, 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/dlm
- Repository: https://github.com/phonepe/dlm

## Overview

PhonePe DLM is a Java library for exclusive distributed locks, with Aerospike and HBase storage adapters. An application initializes the manager, creates a lock identity, attempts immediate or waiting acquisition, performs protected work after acquisition, and releases the lock; the configured TTL handles expiry. LockBase owns retry timing and delegates persistence to the selected store. README capabilities also include DC/XDC levels and custom lock timing. Backend wiring is configurable; the graph reflects documented usage and sampled calls, not unsampled internals.

Main entry points: [`dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockBase.java`](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockBase.java) (Lock orchestration), [`dlm-core/src/main/java/com/phonepe/dlm/DistributedLockManager.java`](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/DistributedLockManager.java) (Lock manager), [`dlm-aerospike/src/main/java/com/phonepe/dlm/aerospike/storage/AerospikeStore.java`](https://github.com/phonepe/dlm/blob/main/dlm-aerospike/src/main/java/com/phonepe/dlm/aerospike/storage/AerospikeStore.java) (Aerospike store), [`dlm-hbase/src/main/java/com/phonepe/dlm/hbase/storage/HBaseStore.java`](https://github.com/phonepe/dlm/blob/main/dlm-hbase/src/main/java/com/phonepe/dlm/hbase/storage/HBaseStore.java) (HBase store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_manager["Lock manager"]
  node_lock["Lock identity<br/>[Lock.java]"]
end

subgraph group_coord["Lock coordination"]
  node_lockbase["Lock orchestration<br/>[LockBase.java]"]
  node_config["Timing config"]
  node_timer["Wait timer<br/>[Timer.java]"]
  node_level["Lock levels<br/>[LockLevel.java]"]
end

subgraph group_stores["Storage backends"]
  node_aerostore["Aerospike store"]
  node_hbasestore["HBase store<br/>[HBaseStore.java]"]
end

node_application(("Application"))
node_aerodb[("Aerospike")]
node_hbasedb[("HBase")]

node_application -->|"initializes and calls"| node_manager
node_manager -->|"creates identity"| node_lock
node_manager -->|"delegates lock operations"| node_lockbase
node_manager -->|"initializes and closes store"| node_lockbase
node_lockbase -->|"reads timings"| node_config
node_lockbase -->|"checks wait timeout"| node_timer
node_lockbase -.->|"writes and removes"| node_aerostore
node_lockbase -.->|"writes and removes"| node_hbasestore
node_aerostore -->|"persists lock records"| node_aerodb
node_hbasestore -->|"creates table and persists"| node_hbasedb
node_aerostore -->|"formats level keys"| node_level
node_hbasestore -->|"formats level keys"| node_level

click node_manager "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/DistributedLockManager.java"
click node_lock "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/Lock.java"
click node_lockbase "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockBase.java"
click node_config "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockConfiguration.java"
click node_timer "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/utils/Timer.java"
click node_level "https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/level/LockLevel.java"
click node_aerostore "https://github.com/phonepe/dlm/blob/main/dlm-aerospike/src/main/java/com/phonepe/dlm/aerospike/storage/AerospikeStore.java"
click node_hbasestore "https://github.com/phonepe/dlm/blob/main/dlm-hbase/src/main/java/com/phonepe/dlm/hbase/storage/HBaseStore.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_manager,node_lock toneBlue
class node_lockbase,node_config,node_timer,node_level,node_aerodb,node_hbasedb toneAmber
class node_aerostore,node_hbasestore toneMint
class node_application toneIndigo
```

## Components

### Application API

- [Lock manager](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/DistributedLockManager.java): `dlm-core/src/main/java/com/phonepe/dlm/DistributedLockManager.java`
- [Lock identity](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/Lock.java): `dlm-core/src/main/java/com/phonepe/dlm/lock/Lock.java`

### Lock coordination

- [Lock orchestration](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockBase.java): `dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockBase.java`
- [Timing config](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockConfiguration.java): `dlm-core/src/main/java/com/phonepe/dlm/lock/base/LockConfiguration.java`
- [Wait timer](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/utils/Timer.java): `dlm-core/src/main/java/com/phonepe/dlm/utils/Timer.java`
- [Lock levels](https://github.com/phonepe/dlm/blob/main/dlm-core/src/main/java/com/phonepe/dlm/lock/level/LockLevel.java): `dlm-core/src/main/java/com/phonepe/dlm/lock/level/LockLevel.java`

### Storage backends

- [Aerospike store](https://github.com/phonepe/dlm/blob/main/dlm-aerospike/src/main/java/com/phonepe/dlm/aerospike/storage/AerospikeStore.java): `dlm-aerospike/src/main/java/com/phonepe/dlm/aerospike/storage/AerospikeStore.java`
- [HBase store](https://github.com/phonepe/dlm/blob/main/dlm-hbase/src/main/java/com/phonepe/dlm/hbase/storage/HBaseStore.java): `dlm-hbase/src/main/java/com/phonepe/dlm/hbase/storage/HBaseStore.java`

### Other components

- **Application**
- **Aerospike**
- **HBase**

## Connections

- Application → Lock manager: initializes and calls
- Lock manager → Lock identity: creates identity
- Lock manager → Lock orchestration: delegates lock operations
- Lock manager → Lock orchestration: initializes and closes store
- Lock orchestration → Timing config: reads timings
- Lock orchestration → Wait timer: checks wait timeout
- Lock orchestration → Aerospike store: writes and removes
- Lock orchestration → HBase store: writes and removes
- Aerospike store → Aerospike: persists lock records
- HBase store → HBase: creates table and persists
- Aerospike store → Lock levels: formats level keys
- HBase store → Lock levels: formats level keys