# niiiizzz/cache_shift architecture

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

- Interactive diagram: https://gitdiagram.com/niiiizzz/cache_shift
- Repository: https://github.com/niiiizzz/cache_shift

## Overview

CacheLab combines a thread-safe LRU/LFU cache library with a workload-simulation server and a live comparison dashboard. Users configure a run or LRU-vs-LFU comparison, the server generates a workload trace and executes it against caches, and the UI receives samples to show rates, counters, progress, charts, and a comparison verdict. The graph preserves the documented workload, TTL, streaming, and dashboard capabilities. Some subsystem links rely on README documentation because their source was not sampled.

Main entry points: [`cache-ui/src/App.tsx`](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/App.tsx) (Dashboard App), [`cache-core/src/main/java/com/cachelab/core/Cache.java`](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/Cache.java) (Cache Container), [`cache-server/src/main/java/com/cachelab/server/service/Run.java`](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/Run.java) (Simulation Run), [`cache-server/src/main/java/com/cachelab/server/service/RunManager.java`](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/RunManager.java) (Run Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Cache Library"]
  node_cache["Cache Container<br/>[Cache.java]"]
  node_builder["Cache Builder<br/>[CacheBuilder.java]"]
  node_entry["Cache Entry<br/>[Entry.java]"]
  node_stats["Cache Statistics<br/>[CacheStats.java]"]
  node_policy["Eviction Contract"]
  node_lru["LRU Policy<br/>[LruPolicy.java]"]
  node_lfu["LFU Policy<br/>[LfuPolicy.java]"]
end

subgraph group_server["Simulation Server"]
  node_controller["Run Controller<br/>[RunController.java]"]
  node_runmanager["Run Manager<br/>[RunManager.java]"]
  node_trace["Trace Generator"]
  node_run["Simulation Run<br/>[Run.java]"]
  node_configmodel["Run Configuration<br/>[RunConfig.java]"]
  node_pattern["Workload Patterns<br/>[Pattern.java]"]
  node_sample["Metric Sample<br/>[Sample.java]"]
  node_exception["Error Handling"]
end

subgraph group_ui["Dashboard"]
  node_app["Dashboard App<br/>[App.tsx]"]
  node_config["Run Configuration<br/>[ConfigPanel.tsx]"]
  node_presets["Workload Presets<br/>[PresetRow.tsx]"]
  node_runapi["Run API Client<br/>[runApi.ts]"]
  node_streamhook["Sample Stream Hook<br/>[useRunStream.ts]"]
  node_metricsview["Metrics Views<br/>[HitRateChart.tsx]"]
  node_verdict["Compare Verdict<br/>[VerdictBanner.tsx]"]
  node_apit["API Types<br/>[api.ts]"]
end

node_user(("Dashboard User"))
node_browser(("Browser"))

node_user -->|"configures and starts"| node_app
node_app -->|"renders"| node_config
node_app -->|"renders"| node_presets
node_app -->|"starts or stops"| node_runapi
node_app -->|"subscribes to"| node_streamhook
node_app -->|"renders metrics"| node_metricsview
node_app -->|"renders comparison"| node_verdict
node_app -->|"uses types"| node_apit
node_runapi -->|"sends REST requests"| node_browser
node_streamhook -->|"polls latest sample"| node_runapi
node_streamhook -->|"opens SSE stream"| node_browser
node_browser -->|"calls REST endpoints"| node_controller
node_controller -->|"starts, stops, retrieves"| node_runmanager
node_controller -->|"registers stream"| node_run
node_runmanager -->|"generates workload"| node_trace
node_runmanager -->|"creates and starts"| node_run
node_runmanager -->|"constructs configurations"| node_configmodel
node_runmanager -->|"configures trace"| node_pattern
node_run -->|"executes operations"| node_cache
node_run -->|"samples counters"| node_stats
node_run -->|"publishes metrics"| node_sample
node_run -->|"streams samples by SSE"| node_browser
node_controller -.->|"maps request errors"| node_exception
node_cache -->|"creates"| node_builder
node_cache -->|"stores and expires"| node_entry
node_cache -->|"updates counters"| node_stats
node_cache -->|"delegates eviction"| node_policy
node_lru -->|"implements"| node_policy
node_lfu -->|"implements"| node_policy
node_cache -.->|"selects by policy"| node_lru
node_cache -.->|"selects by policy"| node_lfu

click node_app "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/App.tsx"
click node_config "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/ConfigPanel.tsx"
click node_presets "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/PresetRow.tsx"
click node_runapi "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/api/runApi.ts"
click node_streamhook "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/hooks/useRunStream.ts"
click node_metricsview "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/HitRateChart.tsx"
click node_verdict "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/VerdictBanner.tsx"
click node_apit "https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/types/api.ts"
click node_controller "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/controller/RunController.java"
click node_runmanager "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/RunManager.java"
click node_trace "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/TraceGenerator.java"
click node_run "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/Run.java"
click node_configmodel "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/RunConfig.java"
click node_pattern "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/Pattern.java"
click node_sample "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/Sample.java"
click node_exception "https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/exception/GlobalExceptionHandler.java"
click node_cache "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/Cache.java"
click node_builder "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/CacheBuilder.java"
click node_entry "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/Entry.java"
click node_stats "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/CacheStats.java"
click node_policy "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/EvictionPolicy.java"
click node_lru "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/LruPolicy.java"
click node_lfu "https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/LfuPolicy.java"

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_cache,node_builder,node_entry,node_stats,node_policy,node_lru,node_lfu,node_user,node_browser toneBlue
class node_controller,node_runmanager,node_trace,node_run,node_configmodel,node_pattern,node_sample,node_exception toneAmber
class node_app,node_config,node_presets,node_runapi,node_streamhook,node_metricsview,node_verdict,node_apit toneMint
```

## Components

### Cache Library

- [Cache Container](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/Cache.java): `cache-core/src/main/java/com/cachelab/core/Cache.java`
- [Cache Builder](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/CacheBuilder.java): `cache-core/src/main/java/com/cachelab/core/CacheBuilder.java`
- [Cache Entry](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/Entry.java): `cache-core/src/main/java/com/cachelab/core/Entry.java`
- [Cache Statistics](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/CacheStats.java): `cache-core/src/main/java/com/cachelab/core/CacheStats.java`
- [Eviction Contract](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/EvictionPolicy.java): `cache-core/src/main/java/com/cachelab/core/policy/EvictionPolicy.java`
- [LRU Policy](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/LruPolicy.java): `cache-core/src/main/java/com/cachelab/core/policy/LruPolicy.java`
- [LFU Policy](https://github.com/niiiizzz/cache_shift/blob/main/cache-core/src/main/java/com/cachelab/core/policy/LfuPolicy.java): `cache-core/src/main/java/com/cachelab/core/policy/LfuPolicy.java`

### Simulation Server

- [Run Controller](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/controller/RunController.java): `cache-server/src/main/java/com/cachelab/server/controller/RunController.java`
- [Run Manager](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/RunManager.java): `cache-server/src/main/java/com/cachelab/server/service/RunManager.java`
- [Trace Generator](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/TraceGenerator.java): `cache-server/src/main/java/com/cachelab/server/service/TraceGenerator.java`
- [Simulation Run](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/service/Run.java): `cache-server/src/main/java/com/cachelab/server/service/Run.java`
- [Run Configuration](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/RunConfig.java): `cache-server/src/main/java/com/cachelab/server/model/RunConfig.java`
- [Workload Patterns](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/Pattern.java): `cache-server/src/main/java/com/cachelab/server/model/Pattern.java`
- [Metric Sample](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/model/Sample.java): `cache-server/src/main/java/com/cachelab/server/model/Sample.java`
- [Error Handling](https://github.com/niiiizzz/cache_shift/blob/main/cache-server/src/main/java/com/cachelab/server/exception/GlobalExceptionHandler.java): `cache-server/src/main/java/com/cachelab/server/exception/GlobalExceptionHandler.java`

### Dashboard

- [Dashboard App](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/App.tsx): `cache-ui/src/App.tsx`
- [Run Configuration](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/ConfigPanel.tsx): `cache-ui/src/components/ConfigPanel.tsx`
- [Workload Presets](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/PresetRow.tsx): `cache-ui/src/components/PresetRow.tsx`
- [Run API Client](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/api/runApi.ts): `cache-ui/src/api/runApi.ts`
- [Sample Stream Hook](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/hooks/useRunStream.ts): `cache-ui/src/hooks/useRunStream.ts`
- [Metrics Views](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/HitRateChart.tsx): `cache-ui/src/components/HitRateChart.tsx`
- [Compare Verdict](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/components/VerdictBanner.tsx): `cache-ui/src/components/VerdictBanner.tsx`
- [API Types](https://github.com/niiiizzz/cache_shift/blob/main/cache-ui/src/types/api.ts): `cache-ui/src/types/api.ts`

### Other components

- **Dashboard User**
- **Browser**

## Connections

- Dashboard User → Dashboard App: configures and starts (evidence: `README.md`)
- Dashboard App → Run Configuration: renders (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → Workload Presets: renders (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → Run API Client: starts or stops (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → Sample Stream Hook: subscribes to (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → Metrics Views: renders metrics (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → Compare Verdict: renders comparison (evidence: `cache-ui/src/App.tsx`)
- Dashboard App → API Types: uses types (evidence: `cache-ui/src/App.tsx`)
- Run API Client → Browser: sends REST requests (evidence: `README.md`)
- Sample Stream Hook → Run API Client: polls latest sample (evidence: `cache-ui/src/hooks/useRunStream.ts`)
- Sample Stream Hook → Browser: opens SSE stream (evidence: `cache-ui/src/hooks/useRunStream.ts`)
- Browser → Run Controller: calls REST endpoints (evidence: `cache-server/src/main/java/com/cachelab/server/controller/RunController.java`)
- Run Controller → Run Manager: starts, stops, retrieves (evidence: `cache-server/src/main/java/com/cachelab/server/controller/RunController.java`)
- Run Controller → Simulation Run: registers stream (evidence: `cache-server/src/main/java/com/cachelab/server/controller/RunController.java`)
- Run Manager → Trace Generator: generates workload (evidence: `cache-server/src/main/java/com/cachelab/server/service/RunManager.java`)
- Run Manager → Simulation Run: creates and starts (evidence: `cache-server/src/main/java/com/cachelab/server/service/RunManager.java`)
- Run Manager → Run Configuration: constructs configurations (evidence: `cache-server/src/main/java/com/cachelab/server/service/RunManager.java`)
- Run Manager → Workload Patterns: configures trace (evidence: `cache-server/src/main/java/com/cachelab/server/service/RunManager.java`)
- Simulation Run → Cache Container: executes operations (evidence: `cache-server/src/main/java/com/cachelab/server/service/Run.java`)
- Simulation Run → Cache Statistics: samples counters (evidence: `cache-server/src/main/java/com/cachelab/server/service/Run.java`)
- Simulation Run → Metric Sample: publishes metrics (evidence: `README.md`)
- Simulation Run → Browser: streams samples by SSE (evidence: `README.md`)
- Run Controller → Error Handling: maps request errors
- Cache Container → Cache Builder: creates (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
- Cache Container → Cache Entry: stores and expires (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
- Cache Container → Cache Statistics: updates counters (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
- Cache Container → Eviction Contract: delegates eviction (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
- LRU Policy → Eviction Contract: implements (evidence: `cache-core/src/main/java/com/cachelab/core/policy/LruPolicy.java`)
- LFU Policy → Eviction Contract: implements (evidence: `cache-core/src/main/java/com/cachelab/core/policy/LfuPolicy.java`)
- Cache Container → LRU Policy: selects by policy (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
- Cache Container → LFU Policy: selects by policy (evidence: `cache-core/src/main/java/com/cachelab/core/Cache.java`)
