# apache/ratis architecture

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

## Overview

##### Main Components Identification
The system should be divided into these major components:

a. Core Components:
- Client Layer (ratis-client/)
- Server Layer (ratis-server/)
- State Machine Interface (ratis-server-api/)
- Common Components (ratis-common/)

b. Communication Protocols:
- gRPC Implementation (ratis-grpc/)
- Netty Implementation (ratis-netty/)
- Protocol Buffers Definitions (ratis-proto/)

c. Supporting Components:
- Metrics System (ratis-metrics-api/, ratis-metrics-default/, ratis-metrics-dropwizard3/)
- Shell Interface (ratis-shell/)
- Tools and Utilities (ratis-tools/)

**[Client Applications]**
- ↕
**[Ratis Client Layer]**
- ↕
**[Communication Layer (gRPC/Netty)]**
- ↕
**[Raft Server Layer]**
- ↕
**[State Machine Interface]**

##### Key Relationships to Highlight

a. Client-Server Communication:
- Both synchronous and asynchronous communication paths
- RPC abstraction layer

b. Consensus Protocol Flow:
- Leader election process
- Log replication
- State machine command application
- Snapshot management

c. Storage and State:
- Raft log storage
- State machine storage
- Snapshot management

##### Detailed Component Breakdown

Client Layer:
**[RaftClient]**
- ↓
**[ClientRpc]**
- ↓
**[RpcType Implementation]**

Server Layer:
**[RaftServer]**
- ↓
**[RaftLog] ← [LogAppender]**
- ↓
**[StateMachine]**

##### Additional Elements

Include:
- Configuration management
- Metrics collection points
- Security layer (TLS)
- Recovery paths
- Snapshot mechanisms

##### Implementation Details

Show:
- Key interfaces (StateMachine, RaftLog)
- Plugin points (RPC, metrics)
- Extension mechanisms
- Configuration options

##### Operational Flows

Illustrate:
- Write path
- Read path
- Leader election
- Log replication
- Snapshot creation/restoration

##### The extensible metrics system

Remember to:
- Keep the core Raft protocol flow clear
- Both control and data paths
- Configuration points
- Monitoring/metrics collection points
- Security boundaries

This design should reflect Ratis's goal of providing a reusable, pluggable Raft implementation while highlighting its support for high-throughput data ingestion and flexible integration options.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style definitions
    classDef core fill:#b3d1ff,stroke:#333,stroke-width:2px
    classDef communication fill:#90EE90,stroke:#333,stroke-width:2px
    classDef storage fill:#FFB366,stroke:#333,stroke-width:2px
    classDef client fill:#FFFF99,stroke:#333,stroke-width:2px
    classDef metrics fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef interface fill:#E6E6FA,stroke:#333,stroke-width:2px

    %% Client Applications Layer
    subgraph ClientApps
        CA[Client Applications]
    end

    %% Client Layer
    subgraph ClientLayer
        RC[RaftClient]:::client
        CR[ClientRpc]:::client
    end

    %% Communication Layer
    subgraph CommLayer
        GRPC[gRPC Implementation]:::communication
        NETTY[Netty Implementation]:::communication
        PROTO[Protocol Buffers]:::communication
    end

    %% Server Layer
    subgraph ServerLayer
        RS[RaftServer]:::core
        RL[RaftLog]:::core
        LA[LogAppender]:::core
    end

    %% State Machine Layer
    subgraph StateMachineLayer
        SM[StateMachine]:::interface
        SS[Snapshot System]:::core
    end

    %% Supporting Components
    subgraph Support
        METRICS[Metrics System]:::metrics
        SHELL[Shell Interface]:::interface
        TOOLS[Tools & Utilities]:::interface
    end

    %% Relationships
    CA --> RC
    RC --> CR
    CR --> GRPC & NETTY
    GRPC & NETTY --> PROTO
    PROTO --> RS
    RS --> RL
    RL --> LA
    RS --> SM
    SM --> SS
    RS --> METRICS
    SHELL --> RS
    TOOLS --> RS

    %% Click events for component mapping
    click RC "https://github.com/apache/ratis/blob/master/ratis-client/src/main/java/org/apache/ratis/client/RaftClient.java"
    click RS "https://github.com/apache/ratis/blob/master/ratis-server-api/src/main/java/org/apache/ratis/server/RaftServer.java"
    click SM "https://github.com/apache/ratis/blob/master/ratis-server-api/src/main/java/org/apache/ratis/statemachine/StateMachine.java"
    click GRPC "https://github.com/apache/ratis/tree/master/ratis-grpc/"
    click NETTY "https://github.com/apache/ratis/tree/master/ratis-netty/"
    click PROTO "https://github.com/apache/ratis/tree/master/ratis-proto/"
    click METRICS "https://github.com/apache/ratis/tree/master/ratis-metrics-api/"
    click SHELL "https://github.com/apache/ratis/tree/master/ratis-shell/"
    click TOOLS "https://github.com/apache/ratis/tree/master/ratis-tools/"

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Communication]:::communication
        L3[Storage]:::storage
        L4[Client]:::client
        L5[Metrics]:::metrics
        L6[Interfaces]:::interface
    end
```
