# scadoshi/steller architecture

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

## Overview

Steller is a Redis-compatible in-memory key-value server. A client sends RESP commands over TCP; per-connection sessions parse and dispatch them, the domain applies cache or channel operations, and replies return in RESP. Mutations are logged, while periodic snapshots provide a recovery baseline; startup restores the snapshot and replays the log. The graph preserves the documented TTL, pub/sub, and graceful-shutdown branches. Some implementation details are unsampled, so their links are omitted rather than inferred.

Main entry points: [`src/lib/inbound/session.rs`](https://github.com/scadoshi/steller/blob/main/src/lib/inbound/session.rs) (Client session), [`src/lib/outbound/persister/mod.rs`](https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/mod.rs) (Persister), [`src/lib/resp/command.rs`](https://github.com/scadoshi/steller/blob/main/src/lib/resp/command.rs) (Command codec), [`src/lib/inbound/server.rs`](https://github.com/scadoshi/steller/blob/main/src/lib/inbound/server.rs) (TCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["TCP sessions"]
  node_server["TCP server<br/>[server.rs]"]
  node_session["Client session<br/>[session.rs]"]
  node_reply_mapping["Reply mapping<br/>[mod.rs]"]
end

subgraph group_protocol["RESP protocol"]
  node_resp_frame["RESP framing<br/>[frame.rs]"]
  node_resp_crlf["CRLF parsing<br/>[crlf.rs]"]
  node_command_codec["Command codec<br/>[command.rs]"]
  node_reply_codec["Reply codec<br/>[reply.rs]"]
end

subgraph group_domain["Domain runtime"]
  node_cache_commands["Cache commands<br/>[write.rs]"]
  node_channel_commands["Channel commands<br/>[channel.rs]"]
  node_cache_service["Cache service<br/>[service.rs]"]
  node_cache[("In-memory cache<br/>[cache.rs]")]
  node_channels[("Pub/sub channels<br/>[channels.rs]")]
  node_time["TTL units<br/>[time.rs]"]
  node_repository_port["Repository port<br/>[ports.rs]"]
end

subgraph group_storage["Persistence"]
  node_persister["Persister<br/>[mod.rs]"]
  node_aof["Append-only log<br/>[aof.rs]"]
  node_snapshot["Snapshot store<br/>[snapshot.rs]"]
  node_persister_inner["File handle<br/>[persister_inner.rs]"]
end

node_client(("Redis client"))

node_client -->|"connects via TCP"| node_server
node_server -->|"spawns per connection"| node_session
node_session -->|"parses frames"| node_resp_frame
node_resp_frame -.->|"uses CRLF parsing"| node_resp_crlf
node_resp_frame -->|"lifts frames"| node_command_codec
node_session -.->|"dispatches commands"| node_command_codec
node_session -->|"executes cache commands"| node_cache_service
node_session -->|"publishes and subscribes"| node_channels
node_command_codec -.->|"creates cache commands"| node_cache_commands
node_command_codec -.->|"creates channel commands"| node_channel_commands
node_cache_service -->|"applies commands"| node_cache
node_cache_service -->|"appends mutations"| node_repository_port
node_cache -->|"uses TTL units"| node_time
node_cache_service -.->|"uses repository adapter"| node_persister
node_persister -->|"implements port"| node_repository_port
node_persister -->|"appends and replays"| node_aof
node_persister -->|"loads and stores"| node_snapshot
node_persister -->|"opens file handles"| node_persister_inner
node_aof -->|"reuses frame codec"| node_resp_frame
node_aof -->|"reuses command parser"| node_command_codec
node_snapshot -->|"serializes cache state"| node_cache
node_session -.->|"maps command outcomes"| node_reply_mapping
node_reply_mapping -->|"constructs RESP replies"| node_reply_codec
node_session -.->|"encodes replies"| node_reply_codec
node_reply_codec -.->|"returns RESP bytes"| node_client
node_server -->|"sweeps expired keys"| node_cache
node_server -->|"recovers and snapshots"| node_persister

click node_server "https://github.com/scadoshi/steller/blob/main/src/lib/inbound/server.rs"
click node_session "https://github.com/scadoshi/steller/blob/main/src/lib/inbound/session.rs"
click node_reply_mapping "https://github.com/scadoshi/steller/blob/main/src/lib/inbound/mod.rs"
click node_resp_frame "https://github.com/scadoshi/steller/blob/main/src/lib/resp/frame.rs"
click node_resp_crlf "https://github.com/scadoshi/steller/blob/main/src/lib/resp/crlf.rs"
click node_command_codec "https://github.com/scadoshi/steller/blob/main/src/lib/resp/command.rs"
click node_reply_codec "https://github.com/scadoshi/steller/blob/main/src/lib/resp/reply.rs"
click node_cache_commands "https://github.com/scadoshi/steller/blob/main/src/lib/domain/command/cache/write.rs"
click node_channel_commands "https://github.com/scadoshi/steller/blob/main/src/lib/domain/command/channel.rs"
click node_cache_service "https://github.com/scadoshi/steller/blob/main/src/lib/domain/service.rs"
click node_cache "https://github.com/scadoshi/steller/blob/main/src/lib/domain/cache.rs"
click node_channels "https://github.com/scadoshi/steller/blob/main/src/lib/domain/channels.rs"
click node_time "https://github.com/scadoshi/steller/blob/main/src/lib/domain/time.rs"
click node_repository_port "https://github.com/scadoshi/steller/blob/main/src/lib/domain/ports.rs"
click node_persister "https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/mod.rs"
click node_aof "https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/aof.rs"
click node_snapshot "https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/snapshot.rs"
click node_persister_inner "https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/persister_inner.rs"

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_server,node_session,node_reply_mapping toneBlue
class node_resp_frame,node_resp_crlf,node_command_codec,node_reply_codec,node_client toneAmber
class node_cache_commands,node_channel_commands,node_cache_service,node_cache,node_channels,node_time,node_repository_port toneMint
class node_persister,node_aof,node_snapshot,node_persister_inner toneRose
```

## Components

### TCP sessions

- [TCP server](https://github.com/scadoshi/steller/blob/main/src/lib/inbound/server.rs): `src/lib/inbound/server.rs`
- [Client session](https://github.com/scadoshi/steller/blob/main/src/lib/inbound/session.rs): `src/lib/inbound/session.rs`
- [Reply mapping](https://github.com/scadoshi/steller/blob/main/src/lib/inbound/mod.rs): `src/lib/inbound/mod.rs`

### RESP protocol

- [RESP framing](https://github.com/scadoshi/steller/blob/main/src/lib/resp/frame.rs): `src/lib/resp/frame.rs`
- [CRLF parsing](https://github.com/scadoshi/steller/blob/main/src/lib/resp/crlf.rs): `src/lib/resp/crlf.rs`
- [Command codec](https://github.com/scadoshi/steller/blob/main/src/lib/resp/command.rs): `src/lib/resp/command.rs`
- [Reply codec](https://github.com/scadoshi/steller/blob/main/src/lib/resp/reply.rs): `src/lib/resp/reply.rs`

### Domain runtime

- [Cache commands](https://github.com/scadoshi/steller/blob/main/src/lib/domain/command/cache/write.rs): `src/lib/domain/command/cache/write.rs`
- [Channel commands](https://github.com/scadoshi/steller/blob/main/src/lib/domain/command/channel.rs): `src/lib/domain/command/channel.rs`
- [Cache service](https://github.com/scadoshi/steller/blob/main/src/lib/domain/service.rs): `src/lib/domain/service.rs`
- [In-memory cache](https://github.com/scadoshi/steller/blob/main/src/lib/domain/cache.rs): `src/lib/domain/cache.rs`
- [Pub/sub channels](https://github.com/scadoshi/steller/blob/main/src/lib/domain/channels.rs): `src/lib/domain/channels.rs`
- [TTL units](https://github.com/scadoshi/steller/blob/main/src/lib/domain/time.rs): `src/lib/domain/time.rs`
- [Repository port](https://github.com/scadoshi/steller/blob/main/src/lib/domain/ports.rs): `src/lib/domain/ports.rs`

### Persistence

- [Persister](https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/mod.rs): `src/lib/outbound/persister/mod.rs`
- [Append-only log](https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/aof.rs): `src/lib/outbound/persister/aof.rs`
- [Snapshot store](https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/snapshot.rs): `src/lib/outbound/persister/snapshot.rs`
- [File handle](https://github.com/scadoshi/steller/blob/main/src/lib/outbound/persister/persister_inner.rs): `src/lib/outbound/persister/persister_inner.rs`

### Other components

- **Redis client**

## Connections

- Redis client → TCP server: connects via TCP (evidence: `README.md`)
- TCP server → Client session: spawns per connection (evidence: `src/lib/inbound/server.rs`)
- Client session → RESP framing: parses frames (evidence: `src/lib/inbound/session.rs`)
- RESP framing → CRLF parsing: uses CRLF parsing
- RESP framing → Command codec: lifts frames (evidence: `src/lib/resp/command.rs`)
- Client session → Command codec: dispatches commands
- Client session → Cache service: executes cache commands (evidence: `src/lib/inbound/session.rs`)
- Client session → Pub/sub channels: publishes and subscribes (evidence: `src/lib/inbound/session.rs`)
- Command codec → Cache commands: creates cache commands
- Command codec → Channel commands: creates channel commands
- Cache service → In-memory cache: applies commands (evidence: `src/lib/domain/service.rs`)
- Cache service → Repository port: appends mutations (evidence: `src/lib/domain/service.rs`)
- In-memory cache → TTL units: uses TTL units (evidence: `src/lib/domain/cache.rs`)
- Cache service → Persister: uses repository adapter (evidence: `README.md`)
- Persister → Repository port: implements port (evidence: `src/lib/outbound/persister/mod.rs`)
- Persister → Append-only log: appends and replays (evidence: `src/lib/outbound/persister/mod.rs`)
- Persister → Snapshot store: loads and stores (evidence: `src/lib/outbound/persister/mod.rs`)
- Persister → File handle: opens file handles (evidence: `src/lib/outbound/persister/persister_inner.rs`)
- Append-only log → RESP framing: reuses frame codec (evidence: `src/lib/outbound/persister/aof.rs`)
- Append-only log → Command codec: reuses command parser (evidence: `src/lib/outbound/persister/aof.rs`)
- Snapshot store → In-memory cache: serializes cache state (evidence: `src/lib/outbound/persister/snapshot.rs`)
- Client session → Reply mapping: maps command outcomes (evidence: `src/lib/inbound/mod.rs`)
- Reply mapping → Reply codec: constructs RESP replies (evidence: `src/lib/inbound/mod.rs`)
- Client session → Reply codec: encodes replies
- Reply codec → Redis client: returns RESP bytes
- TCP server → In-memory cache: sweeps expired keys (evidence: `src/lib/domain/cache.rs`)
- TCP server → Persister: recovers and snapshots (evidence: `src/lib/inbound/server.rs`)
