System Architecture & Design
LoomCache is built from the ground up to be a high-performance distributed cache engine with entirely custom architecture containing zero external cache dependencies. This page explains the inner mechanics.
Architecture Visualized
Section titled “Architecture Visualized”LoomCache Architecture Stack
Zero-dependency, pure Java execution path
1. Client Layer
LoomClient routes request using MurmurHash3 to the correct partition leader.
CP-by-Default Architecture
Section titled “CP-by-Default Architecture”LoomCache implements a CP-by-default (Consistent and Partition-tolerant) architecture under the CAP theorem, similar to etcd and ZooKeeper.
Every single write operation goes through Raft consensus:
- Received by a client and routed to the Raft leader.
- Appended to the leader’s Raft log.
- Replicated to a majority of followers.
- Once acknowledged, the leader advances the
commitIndex. - Applied to the state machine and an acknowledgment is returned to the client.
This strict path guarantees no data loss during network partitions and maintains strict linearizability for all modifications.
Core Layers
Section titled “Core Layers”1. Networking (TcpServer)
Section titled “1. Networking (TcpServer)”LoomCache relies heavily on Java 25 Virtual Threads (Project Loom). The TcpServer spins up a lightweight virtual thread per incoming connection. When the thread performs a blocking I/O operation to read the custom binary protocol bytes, the JVM unmounts the carrier OS thread, allowing a single node to effortlessly handle hundreds of thousands of concurrent connections.
2. Protocol Parser & RBAC
Section titled “2. Protocol Parser & RBAC”Data is transmitted using a highly optimized, custom Kryo-based binary protocol supporting 85 distinct message types. As bytes are parsed into Message objects, the AuthenticationHandler verifies the requested operation against the user’s role-based access control lists (RBAC), instantly dropping unauthorized payloads.
3. Raft Consensus Engine
Section titled “3. Raft Consensus Engine”Our custom RaftNode implementation hardens standard Raft with features like:
- Pre-vote: Prevents partitioned nodes from randomly incrementing election terms and disrupting stable clusters.
- Leader Leases: Lets the Raft leader serve strongly consistent local reads rapidly without needing a quorum validation on every GET.
4. Write-Ahead Log (WAL)
Section titled “4. Write-Ahead Log (WAL)”Memory isn’t infinitely durable. Before any cluster ACK is returned to the user, the WalWriter appends the state change to disk (fsync enabled by default) ensuring total durability even during complete cluster power loss scenarios. Snapshots are taken every 10,000 operations to compact the required recovery logs.