# gregyjames/leaderelection architecture

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

- Interactive diagram: https://gitdiagram.com/gregyjames/leaderelection
- Repository: https://github.com/gregyjames/leaderelection

## Overview

LeaderElection is a .NET library for coordinating one active worker among distributed service instances through interchangeable infrastructure stores. The documented workflow is application configuration and DI registration, starting the election loop, repeatedly running work only while elected leader, then observing leadership/error events and stopping cleanly. The shared base implements election-loop behavior; provider adapters perform store-specific lease or lock operations. Provider implementations are represented from the source index and README; details beyond the shown Blob Storage excerpts are not asserted.

Main entry points: [`src/LeaderElection/LeaderElectionBase.cs`](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/LeaderElectionBase.cs) (Election Loop), [`src/LeaderElection.S3/S3LeaderElection.cs`](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3LeaderElection.cs) (S3 Lease Adapter), [`src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs`](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs) (Blob DI Setup), [`src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs`](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs) (Blob Lease Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Election Core"]
  node_api["Election Contract<br/>[ILeaderElection.cs]"]
  node_engine["Election Loop"]
  node_common_settings["Common Settings"]
end

subgraph group_blob["Blob Storage"]
  node_blob_registration["Blob DI Setup"]
  node_blob_settings["Blob Options"]
  node_blob_election["Blob Lease Adapter"]
  node_azure_blob[("Azure Blob")]
end

subgraph group_cache["Cache Providers"]
  node_redis_registration["Redis DI Setup"]
  node_redis_settings["Redis Options<br/>[RedisSettings.cs]"]
  node_redis_election["Redis Adapter"]
  node_redis[("Redis")]
  node_distributed_registration["Cache DI Setup"]
  node_distributed_settings["Cache Options"]
  node_distributed_election["Cache Adapter"]
  node_distributed_cache[("Distributed Cache")]
  node_fusion_registration["Fusion DI Setup"]
  node_fusion_settings["Fusion Options"]
  node_fusion_election["Fusion Adapter"]
  node_fusion_cache[("FusionCache")]
end

subgraph group_other["Other Stores"]
  node_s3_registration["S3 DI Setup"]
  node_s3_settings["S3 Options<br/>[S3Settings.cs]"]
  node_s3_election["S3 Lease Adapter"]
  node_lease_record["Lease Record<br/>[LeaseRecord.cs]"]
  node_s3[("S3-compatible Store")]
  node_postgres_registration["Postgres DI Setup"]
  node_postgres_settings["Postgres Options"]
  node_postgres_election["Postgres Adapter"]
  node_postgres[("PostgreSQL")]
end

node_application(("Service Instance"))

node_application -.->|"configures"| node_blob_registration
node_application -.->|"configures"| node_redis_registration
node_application -.->|"configures"| node_distributed_registration
node_application -.->|"configures"| node_fusion_registration
node_application -.->|"configures"| node_s3_registration
node_application -.->|"configures"| node_postgres_registration
node_application -->|"starts and uses"| node_api
node_api -->|"implemented by"| node_engine
node_engine -->|"uses"| node_common_settings
node_blob_registration -->|"configures"| node_blob_settings
node_blob_registration -->|"creates"| node_blob_election
node_blob_election -->|"extends"| node_engine
node_blob_election -.->|"acquires and renews leases"| node_azure_blob
node_redis_registration -->|"configures"| node_redis_settings
node_redis_registration -->|"creates"| node_redis_election
node_redis_election -->|"extends"| node_engine
node_redis_election -.->|"uses lock"| node_redis
node_distributed_registration -->|"configures"| node_distributed_settings
node_distributed_registration -->|"creates"| node_distributed_election
node_distributed_election -->|"extends"| node_engine
node_distributed_election -.->|"uses lock"| node_distributed_cache
node_fusion_registration -->|"configures"| node_fusion_settings
node_fusion_registration -->|"creates"| node_fusion_election
node_fusion_election -->|"extends"| node_engine
node_fusion_election -.->|"uses lock"| node_fusion_cache
node_s3_registration -->|"configures"| node_s3_settings
node_s3_registration -->|"creates"| node_s3_election
node_s3_election -->|"extends"| node_engine
node_s3_election -->|"uses"| node_lease_record
node_s3_election -.->|"uses lease object"| node_s3
node_postgres_registration -->|"configures"| node_postgres_settings
node_postgres_registration -->|"creates"| node_postgres_election
node_postgres_election -->|"extends"| node_engine
node_postgres_election -.->|"uses advisory lock"| node_postgres

click node_api "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/ILeaderElection.cs"
click node_engine "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/LeaderElectionBase.cs"
click node_common_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/LeaderElectionSettingsBase.cs"
click node_blob_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs"
click node_blob_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageSettings.cs"
click node_blob_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs"
click node_redis_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisServiceBuilderExtensions.cs"
click node_redis_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisSettings.cs"
click node_redis_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisLeaderElection.cs"
click node_distributed_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheServiceBuilderExtensions.cs"
click node_distributed_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheSettings.cs"
click node_distributed_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheLeaderElection.cs"
click node_fusion_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheServiceBuilderExtensions.cs"
click node_fusion_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheSettings.cs"
click node_fusion_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheLeaderElection.cs"
click node_s3_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3ServiceBuilderExtensions.cs"
click node_s3_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3Settings.cs"
click node_s3_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3LeaderElection.cs"
click node_lease_record "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/LeaseRecord.cs"
click node_postgres_registration "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresServiceBuilderExtensions.cs"
click node_postgres_settings "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresSettings.cs"
click node_postgres_election "https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresLeaderElection.cs"

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_api,node_engine,node_common_settings toneBlue
class node_blob_registration,node_blob_settings,node_blob_election,node_azure_blob toneAmber
class node_redis_registration,node_redis_settings,node_redis_election,node_redis,node_distributed_registration,node_distributed_settings,node_distributed_election,node_distributed_cache,node_fusion_registration,node_fusion_settings,node_fusion_election,node_fusion_cache toneMint
class node_s3_registration,node_s3_settings,node_s3_election,node_lease_record,node_s3,node_postgres_registration,node_postgres_settings,node_postgres_election,node_postgres toneRose
class node_application toneIndigo
```

## Components

### Election Core

- [Election Contract](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/ILeaderElection.cs): `src/LeaderElection/ILeaderElection.cs`
- [Election Loop](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/LeaderElectionBase.cs): `src/LeaderElection/LeaderElectionBase.cs`
- [Common Settings](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection/LeaderElectionSettingsBase.cs): `src/LeaderElection/LeaderElectionSettingsBase.cs`

### Blob Storage

- [Blob DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs): `src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs`
- [Blob Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageSettings.cs): `src/LeaderElection.BlobStorage/BlobStorageSettings.cs`
- [Blob Lease Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs): `src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs`
- **Azure Blob**

### Cache Providers

- [Redis DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisServiceBuilderExtensions.cs): `src/LeaderElection.Redis/RedisServiceBuilderExtensions.cs`
- [Redis Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisSettings.cs): `src/LeaderElection.Redis/RedisSettings.cs`
- [Redis Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Redis/RedisLeaderElection.cs): `src/LeaderElection.Redis/RedisLeaderElection.cs`
- **Redis**
- [Cache DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheServiceBuilderExtensions.cs): `src/LeaderElection.DistributedCache/DistributedCacheServiceBuilderExtensions.cs`
- [Cache Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheSettings.cs): `src/LeaderElection.DistributedCache/DistributedCacheSettings.cs`
- [Cache Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.DistributedCache/DistributedCacheLeaderElection.cs): `src/LeaderElection.DistributedCache/DistributedCacheLeaderElection.cs`
- **Distributed Cache**
- [Fusion DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheServiceBuilderExtensions.cs): `src/LeaderElection.FusionCache/FusionCacheServiceBuilderExtensions.cs`
- [Fusion Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheSettings.cs): `src/LeaderElection.FusionCache/FusionCacheSettings.cs`
- [Fusion Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.FusionCache/FusionCacheLeaderElection.cs): `src/LeaderElection.FusionCache/FusionCacheLeaderElection.cs`
- **FusionCache**

### Other Stores

- [S3 DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3ServiceBuilderExtensions.cs): `src/LeaderElection.S3/S3ServiceBuilderExtensions.cs`
- [S3 Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3Settings.cs): `src/LeaderElection.S3/S3Settings.cs`
- [S3 Lease Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/S3LeaderElection.cs): `src/LeaderElection.S3/S3LeaderElection.cs`
- [Lease Record](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.S3/LeaseRecord.cs): `src/LeaderElection.S3/LeaseRecord.cs`
- **S3-compatible Store**
- [Postgres DI Setup](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresServiceBuilderExtensions.cs): `src/LeaderElection.Postgres/PostgresServiceBuilderExtensions.cs`
- [Postgres Options](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresSettings.cs): `src/LeaderElection.Postgres/PostgresSettings.cs`
- [Postgres Adapter](https://github.com/gregyjames/leaderelection/blob/main/src/LeaderElection.Postgres/PostgresLeaderElection.cs): `src/LeaderElection.Postgres/PostgresLeaderElection.cs`
- **PostgreSQL**

### Other components

- **Service Instance**

## Connections

- Service Instance → Blob DI Setup: configures (evidence: `README.md`)
- Service Instance → Redis DI Setup: configures (evidence: `README.md`)
- Service Instance → Cache DI Setup: configures (evidence: `README.md`)
- Service Instance → Fusion DI Setup: configures (evidence: `README.md`)
- Service Instance → S3 DI Setup: configures (evidence: `README.md`)
- Service Instance → Postgres DI Setup: configures (evidence: `README.md`)
- Service Instance → Election Contract: starts and uses (evidence: `README.md`)
- Election Contract → Election Loop: implemented by (evidence: `src/LeaderElection/LeaderElectionBase.cs`)
- Election Loop → Common Settings: uses (evidence: `src/LeaderElection/LeaderElectionBase.cs`)
- Blob DI Setup → Blob Options: configures (evidence: `src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs`)
- Blob DI Setup → Blob Lease Adapter: creates (evidence: `src/LeaderElection.BlobStorage/BlobStorageServiceBuilderExtensions.cs`)
- Blob Lease Adapter → Election Loop: extends (evidence: `src/LeaderElection.BlobStorage/BlobStorageLeaderElection.cs`)
- Blob Lease Adapter → Azure Blob: acquires and renews leases
- Redis DI Setup → Redis Options: configures (evidence: `src/LeaderElection.Redis/RedisServiceBuilderExtensions.cs`)
- Redis DI Setup → Redis Adapter: creates (evidence: `src/LeaderElection.Redis/RedisServiceBuilderExtensions.cs`)
- Redis Adapter → Election Loop: extends (evidence: `src/LeaderElection.Redis/RedisLeaderElection.cs`)
- Redis Adapter → Redis: uses lock
- Cache DI Setup → Cache Options: configures (evidence: `src/LeaderElection.DistributedCache/DistributedCacheServiceBuilderExtensions.cs`)
- Cache DI Setup → Cache Adapter: creates (evidence: `src/LeaderElection.DistributedCache/DistributedCacheServiceBuilderExtensions.cs`)
- Cache Adapter → Election Loop: extends (evidence: `src/LeaderElection.DistributedCache/DistributedCacheLeaderElection.cs`)
- Cache Adapter → Distributed Cache: uses lock
- Fusion DI Setup → Fusion Options: configures (evidence: `src/LeaderElection.FusionCache/FusionCacheServiceBuilderExtensions.cs`)
- Fusion DI Setup → Fusion Adapter: creates (evidence: `src/LeaderElection.FusionCache/FusionCacheServiceBuilderExtensions.cs`)
- Fusion Adapter → Election Loop: extends (evidence: `src/LeaderElection.FusionCache/FusionCacheLeaderElection.cs`)
- Fusion Adapter → FusionCache: uses lock
- S3 DI Setup → S3 Options: configures (evidence: `src/LeaderElection.S3/S3ServiceBuilderExtensions.cs`)
- S3 DI Setup → S3 Lease Adapter: creates (evidence: `src/LeaderElection.S3/S3ServiceBuilderExtensions.cs`)
- S3 Lease Adapter → Election Loop: extends (evidence: `src/LeaderElection.S3/S3LeaderElection.cs`)
- S3 Lease Adapter → Lease Record: uses (evidence: `src/LeaderElection.S3/S3LeaderElection.cs`)
- S3 Lease Adapter → S3-compatible Store: uses lease object
- Postgres DI Setup → Postgres Options: configures (evidence: `src/LeaderElection.Postgres/PostgresServiceBuilderExtensions.cs`)
- Postgres DI Setup → Postgres Adapter: creates (evidence: `src/LeaderElection.Postgres/PostgresServiceBuilderExtensions.cs`)
- Postgres Adapter → Election Loop: extends (evidence: `src/LeaderElection.Postgres/PostgresLeaderElection.cs`)
- Postgres Adapter → PostgreSQL: uses advisory lock