# muhammadtahanasir/apexkv architecture

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

- Interactive diagram: https://gitdiagram.com/muhammadtahanasir/apexkv
- Repository: https://github.com/muhammadtahanasir/apexkv

## Overview

ApexKV is a Java in-memory cache with Redis-style TCP commands, an interactive CLI, and an HTTP dashboard. The main workflow accepts commands through the TCP server and command processor, then delegates cache operations to the engine and in-memory storage; the dashboard provides a separate HTTP control and inspection surface. The engine also coordinates typed values, eviction, TTL cleanup, persistence, metrics, and messaging. Relationships involving unsampled modules are included only where the README or SOURCE INDEX supports them; the index does not establish every runtime call.

Main entry points: [`src/main/java/com/apexkv/core/CacheEngine.java`](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/CacheEngine.java) (Cache engine), [`src/main/java/com/apexkv/server/DashboardHttpServer.java`](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/DashboardHttpServer.java) (HTTP dashboard), [`src/main/java/com/apexkv/server/CommandProcessor.java`](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/CommandProcessor.java) (Command processor), [`src/main/java/com/apexkv/expiration/ExpirationScheduler.java`](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/expiration/ExpirationScheduler.java) (TTL scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access surfaces"]
  node_tcp["Redis TCP server"]
  node_commands["Command processor"]
  node_cli["Interactive CLI<br/>[MiniRedisCli.java]"]
  node_dashboard["HTTP dashboard"]
end

subgraph group_engine["Cache engine"]
  node_api["Cache API contracts"]
  node_enginecore["Cache engine<br/>[CacheEngine.java]"]
  node_storage[("In-memory storage<br/>[StorageEngine.java]")]
  node_entry["Cache entries<br/>[CacheEntry.java]"]
  node_namespaces["Namespaces"]
  node_values["Typed values"]
end

subgraph group_lifecycle["Cache lifecycle"]
  node_eviction["Eviction strategies"]
  node_expiration["TTL scheduler"]
  node_events["Cache event publisher"]
end

subgraph group_durability["Durability and messaging"]
  node_wal["Write-ahead log<br/>[WriteAheadLog.java]"]
  node_snapshots["Snapshot manager"]
  node_pubsub["Pub/sub engine<br/>[PubSubEngine.java]"]
end

subgraph group_insight["Analytics"]
  node_metrics["Metrics collector"]
  node_memory["Memory statistics<br/>[MemoryStats.java]"]
  node_hotkeys["Hot-key tracker<br/>[HotKeyTracker.java]"]
  node_benchmark["Cache benchmark"]
end

node_client(("Cache client"))
node_operator(("Operator"))

node_client -->|"sends commands"| node_tcp
node_tcp -->|"dispatches commands"| node_commands
node_commands -->|"executes operations"| node_enginecore
node_operator -->|"enters commands"| node_cli
node_cli -->|"uses processor"| node_commands
node_operator -->|"uses dashboard"| node_dashboard
node_dashboard -->|"reads and mutates"| node_enginecore
node_dashboard -->|"runs benchmarks"| node_benchmark
node_enginecore -->|"reads and writes"| node_storage
node_storage -->|"stores entries"| node_entry
node_enginecore -->|"creates values"| node_values
node_enginecore -->|"implements contracts"| node_api
node_commands -->|"uses namespaces"| node_namespaces
node_enginecore -->|"selects policy"| node_eviction
node_enginecore -->|"registers TTL"| node_expiration
node_expiration -->|"removes expired"| node_storage
node_enginecore -->|"publishes changes"| node_events
node_expiration -->|"publishes expiry"| node_events
node_enginecore -->|"logs mutations"| node_wal
node_enginecore -->|"saves snapshots"| node_snapshots
node_commands -->|"publishes messages"| node_pubsub
node_dashboard -->|"publishes messages"| node_pubsub
node_enginecore -->|"owns messaging"| node_pubsub
node_enginecore -->|"records operations"| node_metrics
node_metrics -->|"tracks hot keys"| node_hotkeys
node_enginecore -->|"reports capacity"| node_memory
node_dashboard -.->|"displays analytics"| node_metrics

click node_tcp "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/RedisTcpServer.java"
click node_commands "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/CommandProcessor.java"
click node_cli "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/cli/MiniRedisCli.java"
click node_dashboard "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/DashboardHttpServer.java"
click node_api "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/api/CacheOperations.java"
click node_enginecore "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/CacheEngine.java"
click node_storage "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/StorageEngine.java"
click node_entry "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/CacheEntry.java"
click node_namespaces "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/NamespaceManager.java"
click node_values "https://github.com/muhammadtahanasir/apexkv/tree/main/src/main/java/com/apexkv/value"
click node_eviction "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/eviction/EvictionFactory.java"
click node_expiration "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/expiration/ExpirationScheduler.java"
click node_events "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/event/CacheEventPublisher.java"
click node_wal "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/persistence/WriteAheadLog.java"
click node_snapshots "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/persistence/SnapshotManager.java"
click node_pubsub "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/pubsub/PubSubEngine.java"
click node_metrics "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/MetricsCollector.java"
click node_memory "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/MemoryStats.java"
click node_hotkeys "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/HotKeyTracker.java"
click node_benchmark "https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/benchmark/CacheBenchmark.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_tcp,node_commands,node_cli,node_dashboard toneBlue
class node_api,node_enginecore,node_storage,node_entry,node_namespaces,node_values,node_client toneAmber
class node_eviction,node_expiration,node_events toneMint
class node_wal,node_snapshots,node_pubsub toneRose
class node_metrics,node_memory,node_hotkeys,node_benchmark,node_operator toneIndigo
```

## Components

### Access surfaces

- [Redis TCP server](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/RedisTcpServer.java): `src/main/java/com/apexkv/server/RedisTcpServer.java`
- [Command processor](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/CommandProcessor.java): `src/main/java/com/apexkv/server/CommandProcessor.java`
- [Interactive CLI](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/cli/MiniRedisCli.java): `src/main/java/com/apexkv/cli/MiniRedisCli.java`
- [HTTP dashboard](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/server/DashboardHttpServer.java): `src/main/java/com/apexkv/server/DashboardHttpServer.java`

### Cache engine

- [Cache API contracts](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/api/CacheOperations.java): `src/main/java/com/apexkv/api/CacheOperations.java`
- [Cache engine](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/CacheEngine.java): `src/main/java/com/apexkv/core/CacheEngine.java`
- [In-memory storage](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/StorageEngine.java): `src/main/java/com/apexkv/core/StorageEngine.java`
- [Cache entries](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/CacheEntry.java): `src/main/java/com/apexkv/core/CacheEntry.java`
- [Namespaces](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/core/NamespaceManager.java): `src/main/java/com/apexkv/core/NamespaceManager.java`
- [Typed values](https://github.com/muhammadtahanasir/apexkv/tree/main/src/main/java/com/apexkv/value): `src/main/java/com/apexkv/value`

### Cache lifecycle

- [Eviction strategies](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/eviction/EvictionFactory.java): `src/main/java/com/apexkv/eviction/EvictionFactory.java`
- [TTL scheduler](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/expiration/ExpirationScheduler.java): `src/main/java/com/apexkv/expiration/ExpirationScheduler.java`
- [Cache event publisher](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/event/CacheEventPublisher.java): `src/main/java/com/apexkv/event/CacheEventPublisher.java`

### Durability and messaging

- [Write-ahead log](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/persistence/WriteAheadLog.java): `src/main/java/com/apexkv/persistence/WriteAheadLog.java`
- [Snapshot manager](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/persistence/SnapshotManager.java): `src/main/java/com/apexkv/persistence/SnapshotManager.java`
- [Pub/sub engine](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/pubsub/PubSubEngine.java): `src/main/java/com/apexkv/pubsub/PubSubEngine.java`

### Analytics

- [Metrics collector](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/MetricsCollector.java): `src/main/java/com/apexkv/metrics/MetricsCollector.java`
- [Memory statistics](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/MemoryStats.java): `src/main/java/com/apexkv/metrics/MemoryStats.java`
- [Hot-key tracker](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/metrics/HotKeyTracker.java): `src/main/java/com/apexkv/metrics/HotKeyTracker.java`
- [Cache benchmark](https://github.com/muhammadtahanasir/apexkv/blob/main/src/main/java/com/apexkv/benchmark/CacheBenchmark.java): `src/main/java/com/apexkv/benchmark/CacheBenchmark.java`

### Other components

- **Cache client**
- **Operator**

## Connections

- Cache client → Redis TCP server: sends commands (evidence: `README.md`)
- Redis TCP server → Command processor: dispatches commands (evidence: `src/main/java/com/apexkv/server/RedisTcpServer.java`)
- Command processor → Cache engine: executes operations (evidence: `src/main/java/com/apexkv/server/CommandProcessor.java`)
- Operator → Interactive CLI: enters commands (evidence: `README.md`)
- Interactive CLI → Command processor: uses processor (evidence: `src/main/java/com/apexkv/cli/MiniRedisCli.java`)
- Operator → HTTP dashboard: uses dashboard (evidence: `README.md`)
- HTTP dashboard → Cache engine: reads and mutates (evidence: `src/main/java/com/apexkv/server/DashboardHttpServer.java`)
- HTTP dashboard → Cache benchmark: runs benchmarks (evidence: `src/main/java/com/apexkv/server/DashboardHttpServer.java`)
- Cache engine → In-memory storage: reads and writes (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- In-memory storage → Cache entries: stores entries (evidence: `src/main/java/com/apexkv/core/StorageEngine.java`)
- Cache engine → Typed values: creates values (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Cache engine → Cache API contracts: implements contracts (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Command processor → Namespaces: uses namespaces (evidence: `src/main/java/com/apexkv/server/CommandProcessor.java`)
- Cache engine → Eviction strategies: selects policy (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Cache engine → TTL scheduler: registers TTL (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- TTL scheduler → In-memory storage: removes expired (evidence: `src/main/java/com/apexkv/expiration/ExpirationScheduler.java`)
- Cache engine → Cache event publisher: publishes changes (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- TTL scheduler → Cache event publisher: publishes expiry (evidence: `src/main/java/com/apexkv/expiration/ExpirationScheduler.java`)
- Cache engine → Write-ahead log: logs mutations (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Cache engine → Snapshot manager: saves snapshots (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Command processor → Pub/sub engine: publishes messages (evidence: `src/main/java/com/apexkv/server/CommandProcessor.java`)
- HTTP dashboard → Pub/sub engine: publishes messages (evidence: `src/main/java/com/apexkv/server/DashboardHttpServer.java`)
- Cache engine → Pub/sub engine: owns messaging (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Cache engine → Metrics collector: records operations (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- Metrics collector → Hot-key tracker: tracks hot keys (evidence: `src/main/java/com/apexkv/metrics/MetricsCollector.java`)
- Cache engine → Memory statistics: reports capacity (evidence: `src/main/java/com/apexkv/core/CacheEngine.java`)
- HTTP dashboard → Metrics collector: displays analytics
