# drpcorg/dshackle architecture

> Architecture diagram of the GitHub repository drpcorg/dshackle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drpcorg/dshackle
- Repository: https://github.com/drpcorg/dshackle

## Overview

##### Main Components Overview

The system architecture should be divided into these key layers:

a) External Interface Layer
- gRPC Server (port 2449)
- HTTP/WebSocket Proxy Server (port 8545)
- TLS Security Layer

b) Core Processing Layer
- Request Router
- Load Balancer
- Upstream Manager
- Caching System
- Authentication/Authorization

c) Upstream Connections Layer
- Blockchain Connectors
- Protocol Adapters
- Health Monitors

##### Detailed Component Breakdown

a) Client Interface Components:
- GrpcServer (handles gRPC connections)
- ProxyServer (handles HTTP/WS)
- HttpHandler
- WebsocketHandler
- AuthInterceptor (authentication)

b) Core Processing Components:
- Multistream (manages multiple upstream connections)
- UpstreamAvailability (monitors upstream health)
- CallMethods (manages RPC method routing)
- Caches (handles caching layer)
- BlocksCache
- TxCache
- ReceiptCache

c) Blockchain Specific Components:
- EthereumUpstream
- BitcoinUpstream
- SolanaUpstream
- Other Chain Specific Implementations

##### Data Flow Representation

**Client Request → Authentication → Router → Load Balancer → Upstream Selection →**
**Protocol Translation → Blockchain Node → Response Processing → Caching →**
**Client Response**

##### Integration Points

Integration with:
- Redis (optional caching)
- Multiple blockchain nodes
- Monitoring systems
- TLS termination

##### Key Features to Highlight

Architectural features:
- Fault tolerance mechanisms
- Load balancing strategies
- Caching layers
- Security boundaries
- Protocol translation points

##### Deployment Context

A separate view showing:
- Container boundaries
- Network segments
- Security zones
- High availability pairs

##### Monitoring & Management

Connections to:
- Health check endpoints
- Metrics collection
- Logging infrastructure
- Management APIs

##### Cross-cutting concerns (security, monitoring, caching)

- Hierarchical layouts
- Connector routing
- Export to various formats
- Version control friendly formats

This will create a comprehensive yet understandable representation of Dshackle's architecture that can be easily maintained and updated as the system evolves.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef security fill:#FF6B6B,stroke:#333,stroke-width:2px
    classDef cache fill:#FFD700,stroke:#333,stroke-width:2px
    classDef upstream fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef monitoring fill:#20B2AA,stroke:#333,stroke-width:2px

    %% External Interface Layer
    subgraph ExternalLayer["External Interface Layer"]
        GRPC["gRPC Server\n(Port 2449)"]:::external
        PROXY["HTTP/WS Proxy\n(Port 8545)"]:::external
        TLS["TLS Security"]:::security
        HTTP["HTTP Handler"]:::external
        WS["WebSocket Handler"]:::external
    end

    %% Core Processing Layer
    subgraph CoreLayer["Core Processing Layer"]
        ROUTER["Request Router"]:::core
        LB["Load Balancer"]:::core
        AUTH["Authentication"]:::security
        CACHE["Caching System"]:::cache
        BLOCKS["Blocks Cache"]:::cache
        TX["Transaction Cache"]:::cache
        RECEIPT["Receipt Cache"]:::cache
    end

    %% Upstream Connections Layer
    subgraph UpstreamLayer["Upstream Connections Layer"]
        ETH["Ethereum Upstream"]:::upstream
        BTC["Bitcoin Upstream"]:::upstream
        SOL["Solana Upstream"]:::upstream
        HEALTH["Health Monitor"]:::monitoring
    end

    %% Relationships
    GRPC --> AUTH
    PROXY --> AUTH
    PROXY --> |HTTP Requests| HTTP
    PROXY --> |WS Requests| WS
    HTTP --> ROUTER
    WS --> ROUTER
    AUTH --> ROUTER
    ROUTER --> LB
    LB --> CACHE
    CACHE --> BLOCKS
    CACHE --> TX
    CACHE --> RECEIPT
    LB --> ETH
    LB --> BTC
    LB --> SOL
    HEALTH --> ETH
    HEALTH --> BTC
    HEALTH --> SOL
    TLS --> GRPC
    TLS --> PROXY

    %% Click events
    click GRPC "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/GrpcServer.kt"
    click PROXY "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/proxy/ProxyServer.kt"
    click TLS "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/TlsSetup.kt"
    click ROUTER "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/reader/RequestReaderFactory.kt"
    click LB "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/upstream/Multistream.kt"
    click AUTH "https://github.com/drpcorg/dshackle/tree/master/src/main/kotlin/io/emeraldpay/dshackle/auth"
    click CACHE "https://github.com/drpcorg/dshackle/tree/master/src/main/kotlin/io/emeraldpay/dshackle/cache"
    click ETH "https://github.com/drpcorg/dshackle/tree/master/src/main/kotlin/io/emeraldpay/dshackle/upstream/ethereum"
    click BTC "https://github.com/drpcorg/dshackle/tree/master/src/main/kotlin/io/emeraldpay/dshackle/upstream/bitcoin"
    click SOL "https://github.com/drpcorg/dshackle/tree/master/src/main/kotlin/io/emeraldpay/dshackle/upstream/solana"
    click WS "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/proxy/WebsocketHandler.kt"
    click HTTP "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/proxy/HttpHandler.kt"
    click HEALTH "https://github.com/drpcorg/dshackle/blob/master/src/main/kotlin/io/emeraldpay/dshackle/monitoring/HealthCheckSetup.kt"

    %% Legend
    subgraph Legend
        L1["External Interface"]:::external
        L2["Core Processing"]:::core
        L3["Security Component"]:::security
        L4["Cache Component"]:::cache
        L5["Upstream Component"]:::upstream
        L6["Monitoring"]:::monitoring
    end
```
