# 0jk6/cached architecture

> Architecture diagram of the GitHub repository 0jk6/cached, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0jk6/cached
- Repository: https://github.com/0jk6/cached

## Overview

##### Project Type Analysis
This is a distributed systems project implementing a key-value store with Raft consensus protocol. The main components are:
- Key-value store functionality
- Raft consensus implementation
- HTTP and TCP server interfaces
- Write-ahead logging (WAL) for persistence

##### Main Components

A. Node Components (For each node in the cluster):
- HTTP Server Layer
- TCP Server Layer
- Key-Value Store Cache
- Raft Implementation
- Write-Ahead Log (WAL)

B. Cluster Components:
- Multiple Nodes (at least 3 for Raft)
- Leader Node
- Follower Nodes

**2. Inside, create 3+ node containers (typical Raft deployment)**
**3. Within each node, layer the components:**
- Top: Server Interfaces (HTTP/TCP)
- Middle: Key-Value Store Cache
- Bottom: Raft Implementation + WAL

##### Component Relationships

A. Inter-Node Communication:
- Leader election messages
- Log replication
- Client request forwarding

B. Internal Node Flow:
- Client requests → HTTP/TCP Server
- Server → Cache
- Cache → Raft consensus
- Raft → WAL

##### Specific Elements

- [Node Container]
- [HTTP/TCP Servers] (internal/httpcacheserver.go, internal/tcpcacheserver.go)
- [Cache Layer] (internal/cache.go)
- [Raft Implementation] (internal/raft/raft.go)
- [Write-Ahead Log] (pkg/wal.go)

B. State Indicators:
- Leader/Follower status
- Commit index
- Term number

##### Important Details to Capture
- Leader election flow
- Log replication path
- Client request handling path
- Data persistence flow

##### The multiple server interfaces (HTTP/TCP)

This will create a comprehensive yet understandable representation of the distributed key-value store's architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef server fill:#6495ED,stroke:#333,stroke-width:2px
    classDef cache fill:#90EE90,stroke:#333,stroke-width:2px
    classDef raft fill:#FFD700,stroke:#333,stroke-width:2px
    classDef wal fill:#FFA500,stroke:#333,stroke-width:2px
    classDef leader fill:#FF6B6B,stroke:#333,stroke-width:2px
    classDef follower fill:#A9A9A9,stroke:#333,stroke-width:2px
    
    %% Main Entry
    Main["Main Application"]:::leader
    click Main "https://github.com/0jk6/cached/blob/main/cmd/main.go"

    %% Leader Node
    subgraph Leader["Leader Node"]
        L_HTTP["HTTP Server"]:::server
        L_TCP["TCP Server"]:::server
        L_Cache["Key-Value Cache"]:::cache
        L_Raft["Raft Implementation"]:::raft
        L_WAL["Write-Ahead Log"]:::wal
        
        L_HTTP --> L_Cache
        L_TCP --> L_Cache
        L_Cache --> L_Raft
        L_Raft --> L_WAL
    end
    
    %% Follower Node 1
    subgraph Follower1["Follower Node 1"]
        F1_HTTP["HTTP Server"]:::server
        F1_TCP["TCP Server"]:::server
        F1_Cache["Key-Value Cache"]:::cache
        F1_Raft["Raft Implementation"]:::raft
        F1_WAL["Write-Ahead Log"]:::wal
        
        F1_HTTP --> F1_Cache
        F1_TCP --> F1_Cache
        F1_Cache --> F1_Raft
        F1_Raft --> F1_WAL
    end
    
    %% Follower Node 2
    subgraph Follower2["Follower Node 2"]
        F2_HTTP["HTTP Server"]:::server
        F2_TCP["TCP Server"]:::server
        F2_Cache["Key-Value Cache"]:::cache
        F2_Raft["Raft Implementation"]:::raft
        F2_WAL["Write-Ahead Log"]:::wal
        
        F2_HTTP --> F2_Cache
        F2_TCP --> F2_Cache
        F2_Cache --> F2_Raft
        F2_Raft --> F2_WAL
    end

    %% Component Mappings
    click L_HTTP "https://github.com/0jk6/cached/blob/main/internal/httpcacheserver.go"
    click L_TCP "https://github.com/0jk6/cached/blob/main/internal/tcpcacheserver.go"
    click L_Cache "https://github.com/0jk6/cached/blob/main/internal/cache.go"
    click L_Raft "https://github.com/0jk6/cached/blob/main/internal/raft/raft.go"
    click L_WAL "https://github.com/0jk6/cached/blob/main/pkg/wal.go"
    
    click F1_HTTP "https://github.com/0jk6/cached/blob/main/internal/httpcacheserver.go"
    click F1_TCP "https://github.com/0jk6/cached/blob/main/internal/tcpcacheserver.go"
    click F1_Cache "https://github.com/0jk6/cached/blob/main/internal/cache.go"
    click F1_Raft "https://github.com/0jk6/cached/blob/main/internal/raft/raft.go"
    click F1_WAL "https://github.com/0jk6/cached/blob/main/pkg/wal.go"
    
    click F2_HTTP "https://github.com/0jk6/cached/blob/main/internal/httpcacheserver.go"
    click F2_TCP "https://github.com/0jk6/cached/blob/main/internal/tcpcacheserver.go"
    click F2_Cache "https://github.com/0jk6/cached/blob/main/internal/cache.go"
    click F2_Raft "https://github.com/0jk6/cached/blob/main/internal/raft/raft.go"
    click F2_WAL "https://github.com/0jk6/cached/blob/main/pkg/wal.go"

    %% Inter-node Communications
    Main --> Leader
    L_Raft <--> F1_Raft
    L_Raft <--> F2_Raft
    F1_Raft <--> F2_Raft

    %% Legend
    subgraph Legend
        L1["HTTP/TCP Servers"]:::server
        L2["Cache Layer"]:::cache
        L3["Raft Consensus"]:::raft
        L4["Write-Ahead Log"]:::wal
        L5["Leader Node"]:::leader
        L6["Follower Node"]:::follower
    end
```
