# wrongbyte/rust-paxos architecture

> Architecture diagram of the GitHub repository wrongbyte/rust-paxos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wrongbyte/rust-paxos
- Repository: https://github.com/wrongbyte/rust-paxos

## Overview

Based on our analysis of the file tree and README, this project is a simplified Paxos algorithm simulation written in Rust. It essentially implements a consensus protocol with a “leader” (the proposer that also plays the role of the learner) and a set of acceptor nodes. The goal is to simulate the message-passing steps of the Paxos algorithm (prepare, promise, accept, accepted, learn) in a distributed environment, even though—for simplicity—the simulation is run on a single machine with multiple actors.

- Main Application/Entry Point: Represented by paxos/src/main.rs. This is the starting point that sets up simulated nodes and launches the Paxos negotiation.
- Domain Models: Create a component for the domain logic (paxos/src/domain) that defines the types for messages, nodes, proposals, etc.
- Actors/Node Roles: Show two main actor types:
– Proposer Actor: Implemented in paxos/src/actors/proposer.rs (which also doubles as a Learner per the simplified implementation).
– Acceptor Actor: Found in paxos/src/actors/acceptor.rs.
- Network Communication Layer: Outline the network layer with separate modules for proposers and acceptors under paxos/src/network. This layer manages channels and message routing (note channels and submodules in both proposer and acceptor directories).
- Repository & Utility Modules: Optionally include a component for data persistence or state management (even if currently minimal) from paxos/src/repository.rs.

##### Relationships & Interactions
- That the network module acts as a messaging “bus” that interconnects the actors (e.g., channels in the network modules).

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly separate the domain/business rules (in the domain directory), the actors (in the actors directory), and the network communication layer.
- Layered Architecture: The system can be visually grouped into layers – the “Application” layer (main and configuration), “Business Logic” (actors performing Paxos roles), and “Infrastructure” (network & messaging).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        main["Main (paxos/src/main.rs)"]
        config["Config (paxos/src/config.rs + .envrc)"]
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        domain["Domain Models (paxos/src/domain)"]
        proposer["Proposer/Learner Actor (paxos/src/actors/proposer.rs)"]
        acceptor["Acceptor Actor (paxos/src/actors/acceptor.rs)"]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        netProp["Network: Proposer (paxos/src/network/proposer)"]
        netAcc["Network: Acceptor (paxos/src/network/acceptor)"]
        repo["Repository (paxos/src/repository.rs)"]
    end

    %% Initialization and Dependency Flow
    main --> config
    main --> domain
    main --> proposer
    main --> acceptor
    config --> proposer
    config --> acceptor
    main --> repo

    %% Network channel integration
    proposer -->|"send"| netProp
    netProp -->|"channel"| netAcc
    netAcc -->|"deliver"| acceptor

    %% Paxos message flows between Actors
    proposer -->|"Prepare(n)"| acceptor
    acceptor -->|"Promise(n,v)"| proposer
    proposer -->|"Accept(n,v)"| acceptor
    acceptor -->|"Accepted(n,v)"| proposer
    acceptor -->|"Learn"| proposer

    %% Styling
    classDef application fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef business fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef infrastructure fill:#98FB98,stroke:#32CD32,stroke-width:2px;
    
    class main,config application;
    class domain,proposer,acceptor business;
    class netProp,netAcc,repo infrastructure;

    %% Click Events
    click main "https://github.com/wrongbyte/rust-paxos/blob/main/paxos/src/main.rs"
    click config "https://github.com/wrongbyte/rust-paxos/blob/main/paxos/src/config.rs"
    click domain "https://github.com/wrongbyte/rust-paxos/tree/main/paxos/src/domain"
    click proposer "https://github.com/wrongbyte/rust-paxos/blob/main/paxos/src/actors/proposer.rs"
    click acceptor "https://github.com/wrongbyte/rust-paxos/blob/main/paxos/src/actors/acceptor.rs"
    click netProp "https://github.com/wrongbyte/rust-paxos/tree/main/paxos/src/network/proposer"
    click netAcc "https://github.com/wrongbyte/rust-paxos/tree/main/paxos/src/network/acceptor"
    click repo "https://github.com/wrongbyte/rust-paxos/blob/main/paxos/src/repository.rs"
```
