# afloresc/redis-clone architecture

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

- Interactive diagram: https://gitdiagram.com/afloresc/redis-clone
- Repository: https://github.com/afloresc/redis-clone

## Overview

#### Purpose and Entry Points
GoCache is a Go 1.23+ Redis-compatible in-memory data server. It accepts RESP2 commands over TCP (default port 6380), supports Redis clients, and optionally persists or replicates data. Process startup is `main.go`; server lifecycle and per-connection handling are centered in `internal/core/app.go`.

#### Network Protocol and Dispatch
TCP connections are handled concurrently, decoded from RESP, and routed to command implementations. The router maps the Redis command surface to handlers; command responses are encoded back as RESP.
- `internal/core/app.go`
- `internal/core/router.go`
- `internal/utils/resp.go`

#### Command Execution Layer
The command package is the application-facing API over the store and cross-cutting services. `CommandImpl`/the command interface provide shared command context, while command-family files implement strings, collections, GEO, bitmaps, HyperLogLog, transactions, and pub/sub semantics.
- `internal/command/command.go`
- `internal/command/string.go`
- `internal/command/zset.go`

#### In-Memory Data and Expiration
The store is the authoritative mutable state, holding Redis-compatible typed values and protecting operations with `sync.RWMutex`. TTL management runs as a background expiry-cleanup concern and commands must observe expired-key semantics. This is the key concurrency boundary for normal command execution.
- `internal/store/store.go`
- `internal/store/ttl.go`

#### Transaction and Messaging State
Transactions queue commands for `MULTI` and execute/discard them under transaction rules, including WATCH state. Pub/sub maintains channel and pattern subscriptions and pushes asynchronous messages to subscribed clients, which differs from ordinary request/response command flow.
- `internal/transaction/transaction.go`
- `internal/pubsub/pubsub.go`
- `internal/command/transaction.go`

#### Durability, Capacity, and Replication
Persistence provides two independent durability paths: binary RDB snapshot save/load and append-only command logging with rewrite/fsync behavior. Eviction applies configured LRU/LFU/random/TTL policies when writes exceed memory limits. Replication manages master/slave support and is a boundary for propagating state beyond local memory.
- `internal/persistence/rdb.go`
- `internal/persistence/aof.go`
- `internal/eviction/eviction.go`
- `internal/repl/repl.go`

#### Configuration and Access Control
JSON-backed configuration controls network settings, databases, persistence, eviction, replication, and ACL enablement; runtime Redis `CONFIG` commands expose mutable settings. ACL/authentication establishes connection authorization before protected command access.
- `internal/config/config.go`
- `internal/acl/acl.go`
- `internal/command/string.go`

#### Deployment Runtime
The service is packaged as a standalone Go binary and can run in Docker/Compose. External integration is primarily TCP Redis clients (`redis-cli` and compatible libraries); persistence files are local runtime storage rather than a separate database service.
- `Dockerfile`
- `docker-compose.yml`
- `main.go`

Main entry points: [`internal/config/config.go`](https://github.com/afloresc/redis-clone/blob/main/internal/config/config.go) (Configuration), [`internal/core/app.go`](https://github.com/afloresc/redis-clone/blob/main/internal/core/app.go) (TCP server lifecycle), [`internal/store/store.go`](https://github.com/afloresc/redis-clone/blob/main/internal/store/store.go) (In-memory store), [`internal/command/command.go`](https://github.com/afloresc/redis-clone/blob/main/internal/command/command.go) (Command API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_clients(("Redis clients<br/>external clients"))
  node_main["Process startup<br/>Go entry point<br/>[main.go]"]
  node_deployment["Container runtime<br/>Docker packaging"]
  node_config["Configuration<br/>JSON runtime config<br/>[config.go]"]
end

subgraph group_protocol["Protocol"]
  node_app["TCP server lifecycle<br/>connection server<br/>[app.go]"]
  node_resp["RESP codec<br/>protocol codec<br/>[resp.go]"]
  node_router["Command router<br/>dispatcher<br/>[router.go]"]
end

subgraph group_execution["Command execution"]
  node_commands["Command API<br/>command handlers<br/>[command.go]"]
  node_transactions["Transaction commands<br/>MULTI/WATCH handlers<br/>[transaction.go]"]
  node_acl["ACL and authentication<br/>access control<br/>[acl.go]"]
end

subgraph group_state["Local state"]
  node_store[("In-memory store<br/>typed key-value state<br/>[store.go]")]
  node_ttl["TTL cleanup<br/>expiration worker<br/>[ttl.go]"]
  node_transaction_state["Transaction state<br/>queue and WATCH state<br/>[transaction.go]"]
  node_pubsub["Pub/sub broker<br/>subscription state<br/>[pubsub.go]"]
end

subgraph group_services["Durability and distribution"]
  node_rdb["RDB snapshots<br/>binary persistence<br/>[rdb.go]"]
  node_aof["Append-only log<br/>command persistence<br/>[aof.go]"]
  node_eviction["Eviction policy<br/>memory capacity control<br/>[eviction.go]"]
  node_replication["Replication<br/>[repl.go]"]
end

node_deployment -->|"runs"| node_main
node_main -->|"loads"| node_config
node_main -->|"starts"| node_app
node_config -->|"network settings"| node_app
node_config -->|"ACL enablement"| node_acl
node_config -->|"persistence settings"| node_rdb
node_config -->|"persistence settings"| node_aof
node_config -->|"memory policy"| node_eviction
node_config -->|"replication settings"| node_replication
node_clients -->|"RESP2 over TCP"| node_app
node_app -->|"decode / encode"| node_resp
node_app -->|"authenticate"| node_acl
node_app -->|"dispatch request"| node_router
node_router -->|"routes commands"| node_commands
node_router -->|"routes transaction commands"| node_transactions
node_commands -->|"read and mutate"| node_store
node_commands -->|"publish / subscribe"| node_pubsub
node_transactions -->|"queue and WATCH"| node_transaction_state
node_transactions -->|"execute queued commands"| node_commands
node_ttl -->|"expires keys"| node_store
node_eviction -->|"evicts keys"| node_store
node_rdb -->|"save / restore"| node_store
node_aof -->|"replay / record mutations"| node_store
node_replication -->|"synchronize state"| node_store
node_pubsub -->|"asynchronous messages"| node_clients

click node_main "https://github.com/afloresc/redis-clone/blob/main/main.go"
click node_deployment "https://github.com/afloresc/redis-clone/blob/main/Dockerfile"
click node_config "https://github.com/afloresc/redis-clone/blob/main/internal/config/config.go"
click node_app "https://github.com/afloresc/redis-clone/blob/main/internal/core/app.go"
click node_resp "https://github.com/afloresc/redis-clone/blob/main/internal/utils/resp.go"
click node_router "https://github.com/afloresc/redis-clone/blob/main/internal/core/router.go"
click node_commands "https://github.com/afloresc/redis-clone/blob/main/internal/command/command.go"
click node_transactions "https://github.com/afloresc/redis-clone/blob/main/internal/command/transaction.go"
click node_acl "https://github.com/afloresc/redis-clone/blob/main/internal/acl/acl.go"
click node_store "https://github.com/afloresc/redis-clone/blob/main/internal/store/store.go"
click node_ttl "https://github.com/afloresc/redis-clone/blob/main/internal/store/ttl.go"
click node_transaction_state "https://github.com/afloresc/redis-clone/blob/main/internal/transaction/transaction.go"
click node_pubsub "https://github.com/afloresc/redis-clone/blob/main/internal/pubsub/pubsub.go"
click node_rdb "https://github.com/afloresc/redis-clone/blob/main/internal/persistence/rdb.go"
click node_aof "https://github.com/afloresc/redis-clone/blob/main/internal/persistence/aof.go"
click node_eviction "https://github.com/afloresc/redis-clone/blob/main/internal/eviction/eviction.go"
click node_replication "https://github.com/afloresc/redis-clone/blob/main/internal/repl/repl.go"

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_clients,node_main,node_deployment,node_config toneBlue
class node_app,node_resp,node_router toneAmber
class node_commands,node_transactions,node_acl toneMint
class node_store,node_ttl,node_transaction_state,node_pubsub toneRose
class node_rdb,node_aof,node_eviction,node_replication toneIndigo
```

## Components

### Runtime

- **Redis clients**: external clients · redis-cli and compatible TCP clients.
- [Process startup](https://github.com/afloresc/redis-clone/blob/main/main.go): Go entry point · `main.go`
- [Container runtime](https://github.com/afloresc/redis-clone/blob/main/Dockerfile): Docker packaging · `Dockerfile`
- [Configuration](https://github.com/afloresc/redis-clone/blob/main/internal/config/config.go): JSON runtime config · Controls network, storage, eviction, replication, and ACL settings. · `internal/config/config.go`

### Protocol

- [TCP server lifecycle](https://github.com/afloresc/redis-clone/blob/main/internal/core/app.go): connection server · Accepts concurrent RESP2 connections on the Redis port. · `internal/core/app.go`
- [RESP codec](https://github.com/afloresc/redis-clone/blob/main/internal/utils/resp.go): protocol codec · Decodes requests and encodes command responses. · `internal/utils/resp.go`
- [Command router](https://github.com/afloresc/redis-clone/blob/main/internal/core/router.go): dispatcher · Maps Redis command names to handlers. · `internal/core/router.go`

### Command execution

- [Command API](https://github.com/afloresc/redis-clone/blob/main/internal/command/command.go): command handlers · Shared command context and Redis data-type command families. · `internal/command/command.go`
- [Transaction commands](https://github.com/afloresc/redis-clone/blob/main/internal/command/transaction.go): MULTI/WATCH handlers · Applies transaction rules to queued commands. · `internal/command/transaction.go`
- [ACL and authentication](https://github.com/afloresc/redis-clone/blob/main/internal/acl/acl.go): access control · Authorizes connections before protected command access. · `internal/acl/acl.go`

### Local state

- [In-memory store](https://github.com/afloresc/redis-clone/blob/main/internal/store/store.go): typed key-value state · Authoritative mutable state guarded by sync.RWMutex. · `internal/store/store.go`
- [TTL cleanup](https://github.com/afloresc/redis-clone/blob/main/internal/store/ttl.go): expiration worker · Removes expired keys and supports expired-key semantics. · `internal/store/ttl.go`
- [Transaction state](https://github.com/afloresc/redis-clone/blob/main/internal/transaction/transaction.go): queue and WATCH state · `internal/transaction/transaction.go`
- [Pub/sub broker](https://github.com/afloresc/redis-clone/blob/main/internal/pubsub/pubsub.go): subscription state · Maintains channel and pattern subscriptions and pushes messages. · `internal/pubsub/pubsub.go`

### Durability and distribution

- [RDB snapshots](https://github.com/afloresc/redis-clone/blob/main/internal/persistence/rdb.go): binary persistence · Saves and loads local snapshots. · `internal/persistence/rdb.go`
- [Append-only log](https://github.com/afloresc/redis-clone/blob/main/internal/persistence/aof.go): command persistence · Logs commands with rewrite and fsync behavior. · `internal/persistence/aof.go`
- [Eviction policy](https://github.com/afloresc/redis-clone/blob/main/internal/eviction/eviction.go): memory capacity control · Applies configured LRU, LFU, random, or TTL eviction. · `internal/eviction/eviction.go`
- [Replication](https://github.com/afloresc/redis-clone/blob/main/internal/repl/repl.go): master/slave replication · Propagates state beyond local memory. · `internal/repl/repl.go`

## Connections

- Container runtime → Process startup: runs
- Process startup → Configuration: loads
- Process startup → TCP server lifecycle: starts
- Configuration → TCP server lifecycle: network settings
- Configuration → ACL and authentication: ACL enablement
- Configuration → RDB snapshots: persistence settings
- Configuration → Append-only log: persistence settings
- Configuration → Eviction policy: memory policy
- Configuration → Replication: replication settings
- Redis clients → TCP server lifecycle: RESP2 over TCP
- TCP server lifecycle → RESP codec: decode / encode
- TCP server lifecycle → ACL and authentication: authenticate
- TCP server lifecycle → Command router: dispatch request
- Command router → Command API: routes commands
- Command router → Transaction commands: routes transaction commands
- Command API → In-memory store: read and mutate
- Command API → Pub/sub broker: publish / subscribe
- Transaction commands → Transaction state: queue and WATCH
- Transaction commands → Command API: execute queued commands
- TTL cleanup → In-memory store: expires keys
- Eviction policy → In-memory store: evicts keys
- RDB snapshots → In-memory store: save / restore
- Append-only log → In-memory store: replay / record mutations
- Replication → In-memory store: synchronize state
- Pub/sub broker → Redis clients: asynchronous messages