phalanx

a distributed consensus engine built for high-throughput, low-latency state replication across a 5-node global mesh.

Phalanx is a custom implementation of the Raft consensus protocol in Go, hardened with production extensions (§8, §9.6) and deployed as a 5-node global mesh across Johannesburg, London, Chicago, Singapore, and Frankfurt. It provides a replicated key-value store backed by BadgerDB with automatic peer discovery via SWIM gossip.

Unlike black-box coordination services, Phalanx exposes a transparent, deterministic state machine that decouples consensus logic from I/O. The entire Raft core runs inside a single-threaded event loop with zero mutex contention on the hot path.

at a glance

deterministic core

Pure state machine. No time.Now(), no rand in consensus logic. Fully reproducible execution.

zero-lock hot path

Single-threaded event loop eliminates mutex contention. Predictable sub-millisecond latency.

edge-native

Built-in IPv6 support and SWIM gossip for zero-conf peer discovery on Fly.io.

badgerdb persistence

LSM-tree storage with separate value logs. Optimized for append-heavy Raft workloads.

linearizable reads

Lease-based quorum verification. Reads served locally when leader holds majority lease.

pre-vote protocol

§9.6 extension prevents partitioned nodes from disrupting healthy clusters on rejoin.

quick start

build

go build -ldflags="-s -w" -o phalanx-server ./cmd/server
go build -ldflags="-s -w" -o phalanx ./cmd/phalanx

run a single node

NODE_ID=node-1 DATA_DIR=./data GRPC_ADDR=127.0.0.1:9000 \
  DEBUG_ADDR=127.0.0.1:8080 ./phalanx-server

write and read

phalanx put mykey myvalue -addr 127.0.0.1:9000
phalanx get mykey -addr 127.0.0.1:9000

test suite

31 tests across all packages. Zero flaky tests. The integration test (TestClientKV) starts a real cluster over gRPC, elects a leader, replicates a write, and verifies all nodes converge — in under 500ms. Production runs a 5-node global mesh with Q=3.

$ go test ./... -v -timeout 60s

ok  phalanx          0.48s   (TestClientKV — 3-node integration)
ok  phalanx/raft     0.68s   (17 consensus tests)
ok  phalanx/storage  0.48s   (3 persistence tests)
ok  phalanx/discovery 5.27s  (4 gossip tests)
ok  phalanx/network  0.24s   (8 transport tests)

dependencies

package	purpose
`dgraph-io/badger/v4`	persistent storage (LSM-tree + value log)
`google.golang.org/grpc`	production RPC transport
`hashicorp/memberlist`	SWIM gossip peer discovery

no protoc compiler required. gRPC uses a hand-written JSON codec and service descriptors. no cobra/viper. no prometheus. stdlib only where possible.