# itsmadpig/chat_with_paxos architecture

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

- Interactive diagram: https://gitdiagram.com/itsmadpig/chat_with_paxos
- Repository: https://github.com/itsmadpig/chat_with_paxos

## Overview

This is a command-line chat system backed by servers that replicate committed messages with Paxos. Users submit messages through a client; the load balancer waits for server readiness and assigns clients to the least-loaded live server. Servers commit messages through Paxos and serve log reads; clients periodically refresh logs and retry through the balancer after a server failure. The README also documents server recovery, log catch-up, and simulated delay or disconnection. The main workflow is visible in the excerpts; other RPC protocol details are represented only where the shown code supports them.

Main entry points: [`src/github.com/itsmadpig/server/server_impl.go`](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/server/server_impl.go) (Chat server), [`src/github.com/itsmadpig/paxos/paxos.go`](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxos/paxos.go) (Paxos consensus), [`src/github.com/itsmadpig/client/client.go`](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/client/client.go) (Chat client), [`src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go`](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go) (Load balancer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Client access"]
  node_client["Chat client<br/>[client.go]"]
end

subgraph group_routing["Server routing"]
  node_lb["Load balancer"]
  node_server["Chat server<br/>[server_impl.go]"]
end

subgraph group_replication["Replication"]
  node_paxos["Paxos consensus<br/>[paxos.go]"]
  node_log[("Replicated message log<br/>[paxos.go]")]
end

subgraph group_resilience["Recovery and faults"]
  node_faultwrap["Fault-injection wrapper<br/>[paxosWrap.go]"]
end

node_user(("Chat user"))

node_user -->|"enters messages"| node_client
node_client -->|"requests route"| node_lb
node_lb -->|"returns server address"| node_client
node_client -->|"submits messages"| node_server
node_client -->|"fetches logs"| node_server
node_server -->|"registers server"| node_lb
node_server -->|"proposes messages"| node_paxos
node_server -->|"reads logs"| node_paxos
node_paxos -->|"commits rounds"| node_log
node_paxos -->|"exchanges consensus RPCs"| node_paxos
node_server -->|"catches up on recovery"| node_paxos
node_server -->|"selects test mode"| node_faultwrap
node_faultwrap -->|"delays or delegates"| node_paxos

click node_client "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/client/client.go"
click node_lb "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go"
click node_server "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/server/server_impl.go"
click node_paxos "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxos/paxos.go"
click node_log "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxos/paxos.go"
click node_faultwrap "https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxosTestWrap/paxosWrap.go"

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_client,node_user toneBlue
class node_lb,node_server toneAmber
class node_paxos,node_log toneMint
class node_faultwrap toneRose
```

## Components

### Client access

- [Chat client](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/client/client.go): `src/github.com/itsmadpig/client/client.go`

### Server routing

- [Load balancer](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go): `src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go`
- [Chat server](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/server/server_impl.go): `src/github.com/itsmadpig/server/server_impl.go`

### Replication

- [Paxos consensus](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxos/paxos.go): `src/github.com/itsmadpig/paxos/paxos.go`
- [Replicated message log](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxos/paxos.go): `src/github.com/itsmadpig/paxos/paxos.go`

### Recovery and faults

- [Fault-injection wrapper](https://github.com/itsmadpig/chat_with_paxos/blob/master/src/github.com/itsmadpig/paxosTestWrap/paxosWrap.go): `src/github.com/itsmadpig/paxosTestWrap/paxosWrap.go`

### Other components

- **Chat user**

## Connections

- Chat user → Chat client: enters messages
- Chat client → Load balancer: requests route (evidence: `src/github.com/itsmadpig/client/client.go`)
- Load balancer → Chat client: returns server address (evidence: `src/github.com/itsmadpig/loadbalancer/loadbalancer_impl.go`)
- Chat client → Chat server: submits messages (evidence: `src/github.com/itsmadpig/client/client.go`)
- Chat client → Chat server: fetches logs (evidence: `src/github.com/itsmadpig/client/client.go`)
- Chat server → Load balancer: registers server (evidence: `src/github.com/itsmadpig/server/server_impl.go`)
- Chat server → Paxos consensus: proposes messages (evidence: `src/github.com/itsmadpig/server/server_impl.go`)
- Chat server → Paxos consensus: reads logs (evidence: `src/github.com/itsmadpig/server/server_impl.go`)
- Paxos consensus → Replicated message log: commits rounds (evidence: `src/github.com/itsmadpig/paxos/paxos.go`)
- Paxos consensus → Paxos consensus: exchanges consensus RPCs (evidence: `src/github.com/itsmadpig/paxos/paxos.go`)
- Chat server → Paxos consensus: catches up on recovery (evidence: `src/github.com/itsmadpig/server/server_impl.go`)
- Chat server → Fault-injection wrapper: selects test mode (evidence: `src/github.com/itsmadpig/server/server_impl.go`)
- Fault-injection wrapper → Paxos consensus: delays or delegates (evidence: `src/github.com/itsmadpig/paxosTestWrap/paxosWrap.go`)
