# shivam-pathak9/carrot architecture

> Architecture diagram of the GitHub repository shivam-pathak9/carrot, 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/shivam-pathak9/carrot
- Repository: https://github.com/shivam-pathak9/carrot

## Overview

Carrot is a single-node, in-memory Redis-inspired server. A client sends RESP commands to either the goroutine-per-connection server or the Linux epoll reactor; requests are parsed, dispatched to command handlers, applied to typed storage, and answered in RESP. The README documents string and list operations, TTL expiration, and both networking models. Reactor internals are represented from the sampled excerpts and SOURCE INDEX; some event-loop-to-connection details are not directly shown, so that link is marked unverified.

Main entry points: [`internal/server/server.go`](https://github.com/shivam-pathak9/carrot/blob/master/internal/server/server.go) (Goroutine server), [`internal/reactor/server.go`](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/server.go) (Reactor server), [`internal/reactor/connection.go`](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/connection.go) (Socket connection cycle), [`internal/command/executor.go`](https://github.com/shivam-pathak9/carrot/blob/master/internal/command/executor.go) (Command dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtimes"]
  node_standard_entry["TCP server binary<br/>[main.go]"]
  node_standard_server["Goroutine server<br/>[server.go]"]
  node_reactor_entry["Reactor binary<br/>[main.go]"]
  node_reactor_server["Reactor server<br/>[server.go]"]
  node_event_loop["Epoll event loop<br/>[event_loop.go]"]
  node_connection["Socket connection cycle<br/>[connection.go]"]
  node_poller["Epoll poller<br/>[poller.go]"]
end

subgraph group_command["Command handling"]
  node_parser["Command parser<br/>[parser.go]"]
  node_executor["Command dispatcher<br/>[executor.go]"]
  node_string_commands["String and TTL commands"]
  node_list_commands["List commands<br/>[list.go]"]
end

subgraph group_data["Protocol and storage"]
  node_client_io["Buffered client I/O<br/>[client.go]"]
  node_resp["RESP framing<br/>[decoder.go]"]
  node_storage[("In-memory key store<br/>[storage.go]")]
  node_list_storage["List storage<br/>[list.go]"]
end

subgraph group_ops["Configuration and expiry"]
  node_config["Server configuration<br/>[config.go]"]
end

node_client_actor(("Redis client"))

node_client_actor -->|"connects to"| node_standard_entry
node_client_actor -->|"connects to"| node_reactor_entry
node_standard_entry -->|"starts"| node_standard_server
node_standard_entry -->|"loads"| node_config
node_standard_server -->|"wraps connection"| node_client_io
node_client_io -->|"decodes and encodes"| node_resp
node_standard_server -->|"parses requests"| node_parser
node_standard_server -->|"executes commands"| node_executor
node_parser -->|"reads values"| node_resp
node_reactor_entry -->|"starts"| node_reactor_server
node_reactor_entry -->|"loads"| node_config
node_reactor_server -->|"creates and registers"| node_poller
node_reactor_server -->|"runs"| node_event_loop
node_event_loop -.->|"dispatches readiness"| node_connection
node_connection -->|"parses requests"| node_parser
node_connection -->|"executes commands"| node_executor
node_connection -->|"decodes and encodes"| node_resp
node_executor -->|"dispatches"| node_string_commands
node_executor -->|"dispatches"| node_list_commands
node_string_commands -->|"reads and writes"| node_storage
node_list_commands -->|"reads and writes"| node_list_storage
node_standard_server -->|"creates and expires"| node_storage
node_reactor_server -->|"creates store"| node_storage
node_event_loop -->|"runs expiry sweep"| node_storage
node_standard_server -->|"uses limits"| node_config
node_reactor_server -->|"uses limits"| node_config

click node_standard_entry "https://github.com/shivam-pathak9/carrot/blob/master/cmd/server/main.go"
click node_standard_server "https://github.com/shivam-pathak9/carrot/blob/master/internal/server/server.go"
click node_client_io "https://github.com/shivam-pathak9/carrot/blob/master/internal/client/client.go"
click node_reactor_entry "https://github.com/shivam-pathak9/carrot/blob/master/cmd/reactor-server/main.go"
click node_reactor_server "https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/server.go"
click node_event_loop "https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/event_loop.go"
click node_connection "https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/connection.go"
click node_poller "https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/poller.go"
click node_resp "https://github.com/shivam-pathak9/carrot/blob/master/internal/protocol/resp/decoder.go"
click node_parser "https://github.com/shivam-pathak9/carrot/blob/master/internal/command/parser.go"
click node_executor "https://github.com/shivam-pathak9/carrot/blob/master/internal/command/executor.go"
click node_string_commands "https://github.com/shivam-pathak9/carrot/tree/master/internal/command"
click node_list_commands "https://github.com/shivam-pathak9/carrot/blob/master/internal/command/list.go"
click node_storage "https://github.com/shivam-pathak9/carrot/blob/master/internal/storage/storage.go"
click node_list_storage "https://github.com/shivam-pathak9/carrot/blob/master/internal/storage/list.go"
click node_config "https://github.com/shivam-pathak9/carrot/blob/master/internal/config/config.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_standard_entry,node_standard_server,node_reactor_entry,node_reactor_server,node_event_loop,node_connection,node_poller toneBlue
class node_parser,node_executor,node_string_commands,node_list_commands,node_client_actor toneAmber
class node_client_io,node_resp,node_storage,node_list_storage toneMint
class node_config toneRose
```

## Components

### Server runtimes

- [TCP server binary](https://github.com/shivam-pathak9/carrot/blob/master/cmd/server/main.go): `cmd/server/main.go`
- [Goroutine server](https://github.com/shivam-pathak9/carrot/blob/master/internal/server/server.go): `internal/server/server.go`
- [Reactor binary](https://github.com/shivam-pathak9/carrot/blob/master/cmd/reactor-server/main.go): `cmd/reactor-server/main.go`
- [Reactor server](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/server.go): `internal/reactor/server.go`
- [Epoll event loop](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/event_loop.go): `internal/reactor/event_loop.go`
- [Socket connection cycle](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/connection.go): `internal/reactor/connection.go`
- [Epoll poller](https://github.com/shivam-pathak9/carrot/blob/master/internal/reactor/poller.go): `internal/reactor/poller.go`

### Command handling

- [Command parser](https://github.com/shivam-pathak9/carrot/blob/master/internal/command/parser.go): `internal/command/parser.go`
- [Command dispatcher](https://github.com/shivam-pathak9/carrot/blob/master/internal/command/executor.go): `internal/command/executor.go`
- [String and TTL commands](https://github.com/shivam-pathak9/carrot/tree/master/internal/command): `internal/command`
- [List commands](https://github.com/shivam-pathak9/carrot/blob/master/internal/command/list.go): `internal/command/list.go`

### Protocol and storage

- [Buffered client I/O](https://github.com/shivam-pathak9/carrot/blob/master/internal/client/client.go): `internal/client/client.go`
- [RESP framing](https://github.com/shivam-pathak9/carrot/blob/master/internal/protocol/resp/decoder.go): `internal/protocol/resp/decoder.go`
- [In-memory key store](https://github.com/shivam-pathak9/carrot/blob/master/internal/storage/storage.go): `internal/storage/storage.go`
- [List storage](https://github.com/shivam-pathak9/carrot/blob/master/internal/storage/list.go): `internal/storage/list.go`

### Configuration and expiry

- [Server configuration](https://github.com/shivam-pathak9/carrot/blob/master/internal/config/config.go): `internal/config/config.go`

### Other components

- **Redis client**

## Connections

- Redis client → TCP server binary: connects to (evidence: `README.md`)
- Redis client → Reactor binary: connects to (evidence: `README.md`)
- TCP server binary → Goroutine server: starts (evidence: `cmd/server/main.go`)
- TCP server binary → Server configuration: loads (evidence: `cmd/server/main.go`)
- Goroutine server → Buffered client I/O: wraps connection (evidence: `internal/server/server.go`)
- Buffered client I/O → RESP framing: decodes and encodes (evidence: `internal/client/client.go`)
- Goroutine server → Command parser: parses requests (evidence: `internal/server/server.go`)
- Goroutine server → Command dispatcher: executes commands (evidence: `internal/server/server.go`)
- Command parser → RESP framing: reads values (evidence: `internal/command/parser.go`)
- Reactor binary → Reactor server: starts (evidence: `cmd/reactor-server/main.go`)
- Reactor binary → Server configuration: loads (evidence: `cmd/reactor-server/main.go`)
- Reactor server → Epoll poller: creates and registers (evidence: `internal/reactor/server.go`)
- Reactor server → Epoll event loop: runs (evidence: `internal/reactor/server.go`)
- Epoll event loop → Socket connection cycle: dispatches readiness
- Socket connection cycle → Command parser: parses requests (evidence: `internal/reactor/connection.go`)
- Socket connection cycle → Command dispatcher: executes commands (evidence: `internal/reactor/connection.go`)
- Socket connection cycle → RESP framing: decodes and encodes (evidence: `internal/reactor/connection.go`)
- Command dispatcher → String and TTL commands: dispatches (evidence: `internal/command/executor.go`)
- Command dispatcher → List commands: dispatches (evidence: `internal/command/executor.go`)
- String and TTL commands → In-memory key store: reads and writes (evidence: `internal/command/set.go`)
- List commands → List storage: reads and writes (evidence: `internal/command/list.go`)
- Goroutine server → In-memory key store: creates and expires (evidence: `internal/server/server.go`)
- Reactor server → In-memory key store: creates store (evidence: `internal/reactor/server.go`)
- Epoll event loop → In-memory key store: runs expiry sweep (evidence: `README.md`)
- Goroutine server → Server configuration: uses limits (evidence: `internal/server/server.go`)
- Reactor server → Server configuration: uses limits (evidence: `internal/reactor/server.go`)
