# santanusinha/dropwizard-db-sharding-bundle architecture

> Architecture diagram of the GitHub repository santanusinha/dropwizard-db-sharding-bundle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santanusinha/dropwizard-db-sharding-bundle
- Repository: https://github.com/santanusinha/dropwizard-db-sharding-bundle

## Overview

##### Main Components Identification
- Sharding Bundles – The core classes (e.g., DBShardingBundle, MultiTenantDBShardingBundle, BalancedDBShardingBundle) in the package indicate that the library supports various sharding strategies.
- Sharding Logic Module – This includes the hashing (using Guava’s murmur3_128), bucket-to-shard mapping logic (using a 1024 bucket default), and the logic used to calculate the target shard.
- Data Access Objects (DAOs) – There are multiple DAO implementations (RelationalDao, LookupDao, CacheableLookupDao, CacheableRelationalDao) that serve as a layer above Hibernate.
- Cache Modules – Components such as LookupCache and RelationalCache abstract the caching layer (supporting integrations with Caffeine/Guava caches).
- Administration and Health Check Components – Such as Shard blacklisting tasks, BlacklistingStore interface, and health check classes that ensure the operational status of shards.
- Utility and Support Components – Including transaction execution, filtering (TransactionFilter), listeners, observers, and metrics to observe operations and record system behavior.

##### Relationships and Interactions
- The dropwizard bundle initializes and configures the sharding logic at application startup by determining the number and mapping of physical shards.
- Business data flows from the application to the DAOs. The DAOs use the sharding logic to calculate the correct shard (bucket mapping, then shard selection) before interacting with the database via Hibernate sessions.
- The caching wrappers (CacheableLookupDao & CacheableRelationalDao) intercept DAO calls to provide read-through/write-through behavior.
- Administrative components allow runtime management features such as blacklisting problematic shards. Health checks monitor the state of shards.
- The DAO operations (such as Save, Get, Select, and Update) are broken down into operations classes that implement specific transactional or query behaviors.

##### Architectural Patterns and Design Principles
- Separation of Concerns – Sharding mechanisms, data access, caching, and administration are clearly separated into different packages and classes.
- Plugin/Extensibility Model – With interfaces like ShardBlacklistingStore, custom cache implementations, and transaction observers, the framework is designed to be extensible.
- Modular design – Each component (e.g., sharding, caching, DAO operations) has its dedicated package and sub-packages, which helps in understanding and maintaining the code.
- Dropwizard Integration – The bundle is designed to integrate with Dropwizard, leveraging its configuration, lifecycle, and health check mechanisms.

##### Essential Elements
- Interaction paths for resharding scenarios: Optionally include an annotation or note showing the resharding process when the number of physical shards changes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        A["Dropwizard Application"]:::app
    end

    %% Dropwizard Sharding Bundle
    subgraph "Dropwizard Sharding Bundle"
        direction TB
        SB["DBShardingBundle"]:::bundle
        MT["MultiTenantDBShardingBundle"]:::bundle
        BS["BalancedDBShardingBundle"]:::bundle
    end

    %% Sharding Logic Module
    subgraph "Sharding Logic Module"
        direction TB
        BSM["BalancedShardManager"]:::logic
        BEX["BucketIdExtractor"]:::logic
        SC["ShardCalculator"]:::logic
    end

    %% DAO Layer
    subgraph "DAO Layer"
        direction TB
        RD["RelationalDao"]:::dao
        LD["LookupDao"]:::dao
        CRD["CacheableRelationalDao"]:::dao
        CLD["CacheableLookupDao"]:::dao
    end

    %% Cache Modules
    subgraph "Cache Modules"
        direction TB
        LC["LookupCache"]:::cache
        RC["RelationalCache"]:::cache
    end

    %% Administration & Health Check
    subgraph "Administration & Health Check"
        direction TB
        subgraph "Admin Tasks"
            BLS["BlacklistShardTask"]:::admin
            UBS["UnblacklistShardTask"]:::admin
        end
        subgraph "Health Checks"
            BAH["BlacklistingAwareHealthCheck"]:::admin
            HCM["HealthCheckManager"]:::admin
        end
    end

    %% Utility & Support
    subgraph "Utility & Support"
        direction TB
        TE["TransactionExecutor"]:::util
        TEC["TransactionExecutionContext"]:::util
        TF["TransactionFilter"]:::util
        TL["TransactionListener"]:::util
        TMM["TransactionMetricManager"]:::util
        TO["TransactionObserver"]:::util
    end

    %% Physical Database Shards
    PD["Physical DB Shards"]:::db

    %% Data Flow Connections
    A -->|"initialize"| SB
    A -->|"initialize"| MT
    A -->|"initialize"| BS

    SB -->|"configure"| BSM
    MT -->|"configure"| BSM
    BS -->|"configure"| BSM

    BSM -->|"uses"| BEX
    BEX -->|"computes"| SC

    SC -->|"determines shard for"| RD
    SC -->|"determines shard for"| LD

    RD -->|"Hibernate Session"| PD
    LD -->|"Hibernate Session"| PD
    RD -->|"wrapped by"| CRD
    LD -->|"wrapped by"| CLD

    LC -.->|"cache lookup"| RD
    RC -.->|"cache lookup"| LD

    BAH -.->|"feedback"| BSM
    HCM -.->|"health manage"| BSM

    TE -.->|"transaction execution"| RD
    TEC -.->|"transaction context"| RD
    TF -.->|"filter operations"| RD
    TL -.->|"listen events"| RD
    TMM -.->|"record metrics"| RD
    TO -.->|"observe transactions"| RD

    BLS -.->|"blacklisting override"| BSM
    UBS -.->|"blacklisting override"| BSM

    %% Click Events
    click SB "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/DBShardingBundle.java"
    click MT "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/MultiTenantDBShardingBundle.java"
    click BS "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/BalancedDBShardingBundle.java"
    click BSM "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/sharding/BalancedShardManager.java"
    click BEX "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/sharding/BucketIdExtractor.java"
    click SC "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/utils/ShardCalculator.java"
    click RD "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/dao/RelationalDao.java"
    click LD "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/dao/LookupDao.java"
    click CRD "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/dao/CacheableRelationalDao.java"
    click CLD "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/dao/CacheableLookupDao.java"
    click LC "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/caching/LookupCache.java"
    click RC "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/caching/RelationalCache.java"
    click BLS "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/admin/BlacklistShardTask.java"
    click UBS "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/admin/UnblacklistShardTask.java"
    click BAH "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/healthcheck/BlacklistingAwareHealthCheck.java"
    click HCM "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/healthcheck/HealthCheckManager.java"
    click TE "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/execution/TransactionExecutor.java"
    click TEC "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/execution/TransactionExecutionContext.java"
    click TF "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/filters/TransactionFilter.java"
    click TL "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/listeners/TransactionListener.java"
    click TMM "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/metrics/TransactionMetricManager.java"
    click TO "https://github.com/santanusinha/dropwizard-db-sharding-bundle/blob/master/src/main/java/io/appform/dropwizard/sharding/observers/TransactionObserver.java"

    %% Styles
    classDef app fill:#f9c,stroke:#333,stroke-width:2px;
    classDef bundle fill:#bbf,stroke:#333,stroke-width:2px;
    classDef logic fill:#afa,stroke:#333,stroke-width:2px;
    classDef dao fill:#ffd,stroke:#333,stroke-width:2px;
    classDef cache fill:#fea,stroke:#333,stroke-width:2px;
    classDef admin fill:#fdd,stroke:#333,stroke-width:2px;
    classDef util fill:#eef,stroke:#333,stroke-width:2px;
    classDef db fill:#cfc,stroke:#333,stroke-width:2px;
```
