Architecture

System Overview

┌──────────────────────────────────────────────────────────┐
│                    Client Application                     │
│                    (TCP Connection)                        │
└─────────────────────┬────────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────────┐
│                   CacheServer                             │
│                   (TCP Listener)                          │
├──────────────────────────────────────────────────────────┤
│  Protocol Parser → Request Router → Response Serializer  │
└─────────────────────┬────────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────────┐
│              ConsistentHash (Hash Ring)                   │
│  key → hash(key) → find responsible node                 │
└──────┬──────────────┬──────────────┬─────────────────────┘
       │              │              │
┌──────▼──────┐ ┌─────▼──────┐ ┌────▼───────┐
│   Node 0    │ │   Node 1   │ │   Node 2   │
│  (RAM Store)│ │  (RAM Store)│ │  (RAM Store)│
│  + LRU      │ │  + LRU     │ │  + LRU     │
│  + TTL      │ │  + TTL     │ │  + TTL     │
│  + Persist  │ │  + Persist │ │  + Persist │
└─────────────┘ └────────────┘ └────────────┘
       │              │              │
       └──────────────┼──────────────┘
                      │
              ┌───────▼───────┐
              │  Replication  │
              │  (Cross-node) │
              └───────────────┘

Module Dependencies

Module 1: Core (types, hashing, node)
    ↓
Module 2: Strategies (LRU, LFU, FIFO)
    ↓
Module 3: Network (protocol, server, client)
    ↓
Module 4: Cluster (election, failover)
    ↓
Module 5: Replication
    ↓
Module 6: Invalidation
    ↓
Module 7: Benchmark
    ↓
Module 8: Visualization

Data Flow

Write Path (SET)

1. Client sends: SET key value ttl
2. Protocol parser extracts key, value, ttl
3. ConsistentHash finds responsible node
4. Node.set(key, value, ttl)
   ├── Check if key exists → update eviction
   ├── Create CacheEntry with TTL
   ├── Store in Map
   └── Enforce maxSize (evict if full)
5. ReplicationManager replicates to backup nodes
6. Response: OK

Read Path (GET)

1. Client sends: GET key
2. Protocol parser extracts key
3. ConsistentHash finds responsible node
4. Node.get(key)
   ├── Check if key exists
   ├── Check if expired (TTL)
   ├── Update access stats
   └── Return value
5. Response: VALUE data

Tech Stack

Layer	Technology	Why
Language	TypeScript	Type safety, IDE support
Runtime	Node.js	Ecosystem, compatibility
Hash	murmurhash	Fast, good distribution
Network	TCP sockets	Low latency, Redis-compatible
Frontend	React + Canvas	Popular, efficient rendering
Testing	Jest	Industry standard
CI/CD	GitHub Actions	Free, integrated
Build	tsup	Fast bundler