ARCHITECTURE

Inside the
Thunder engine.

Local execution. Room for large values. Writes that survive a restart.

See how Thunder brings CPU, memory, and persistent storage together.

01 / EXECUTIONKeep work local.

Each reactor handles its own shard range.

02 / MEMORYGive values room.

Dedicated arenas hold working data and cached values.

03 / PERSISTENCEMake writes last.

The journal reaches disk before success is returned.

A direct path to the owner.

01 / THE WHOLE ENGINE

Explore an allocation 8 cores · 2 threads/core

Example allocations. Thunder derives its reactor count from the host’s usable CPU topology.

Logical shard
0892
Owning reactor
R06
Listening port
7386

Shard 0892 → reactor R06 → port 7386

Client → owner illustrative timing

YOUR APPLICATION

Official client

Starts with one address. Discovers shard ranges and their serving ports.

CRC32C(key) % 1024Shard 0892

THE OWNING REACTOR

Reactor 06

Port 7386

Local execution

Handles requests for its shard range.

ITS OWN ARENAWorking memory

Request space + cached values

Persistent storage

Shard files

Stored values and index

Reactor journal

On disk before write acknowledgement

Owns logical shards 768–895

The client sends requests directly to the discovered owner. The drawing shows ownership and I/O connections; read and write paths are explained below.
Explore all 1,024 logical shards 8 owners
FIXED KEYSPACESHARD RANGES

One mark per shard. The highlighted mark belongs to the selected key. Changing the allocation moves ownership; it does not change the key’s shard.

A local illustration using Thunder’s key hash and uniform CPU topology. Changing the allocation changes ownership; the key’s logical shard stays fixed. No database connection is made.

02 / EXECUTION

Inside one owner.

Keep the request with the reactor responsible for its data. Its foreground execution, local arena, and asynchronous I/O form the working path.

REACTOR 06LOGICAL VIEW
HARDWARE THREAD AForeground reactor

Requests for the owned shard range

HARDWARE THREAD BBackground workers

Shared by maintenance and journal work

REACTOR-LOCAL ARENARequest working space · cached values
Asynchronous disk + network I/Oio_uring
Each reactor group uses two hardware threads. The group can contain multiple software threads; CPU topology determines how those hardware threads are allocated.

GET / READ

Return the value.

A cached value can be returned directly. On a cache miss, the engine looks up the value and reads it from storage.

Cache hitResponse
Cache missIndex + disk read Response

A value read from disk is decrypted and may be admitted to the cache.

SET / WRITE

Make the write durable.

The owning reactor handles the write using its arena and storage. Its journal record reaches disk before success is returned.

Owning reactorJournal durable acknowledgement
Follow the durability boundary

The client knows the way.

The official client starts with one address, obtains ranges, ports, and a routing epoch through DISCOVER, then connects directly to the owners. Every discovered port must be reachable on the same host and port number.

Connect your application

03 / LARGE VALUES

Keep the whole value.

Store a complete application object under one key, including values of 512 MiB and more. Size each reactor’s arena for the objects and concurrent requests it will handle.

CONFIGURED ARENA / REACTOR4 GiB

This arena serves the reactor’s requests and cached values. The example below shows the value copies needed by one 512 MiB write within it.

One reactor’s resident arena
A + B Two copies × 512 MiB = 1 GiB of value bytes
4 GiB is the documented arena setting per reactor for this workload, not an allocation per value. Other arena needs and concurrent requests share the working budget. The drawing illustrates sizing rather than physical memory placement.

MEMORY

Resident from boot.

Arenas are fully resident. Budget arena bytes × reactor count, then add process overhead. The documented setting for 512 MiB values is THUNDERSTRIKE_ARENA_BYTES=4294967296.

NETWORK + DISK

Size the rest of the path.

The official client pipelines requests and multiplexes large values. Plan disk capacity at peak live bytes / 0.75, plus one 4 GiB chunk for workloads with values of 512 MiB or more.

Read the capacity planning reference

04 / DURABILITY

What “written” means.

Every acknowledged write has a journal record on disk. The documented durability contract covers acknowledged writes surviving a crash or power cut.

  1. REQUEST

    Write received.

    The owning reactor handles the request.

  2. DURABILITY BOUNDARY

    Journal on disk.

    The journal record is durable before success is returned.

  3. RESPONSE

    Write acknowledged.

    Your application receives the successful response.

The acknowledgement guarantee, shown in order. Internal write operations may overlap.

AFTER A RESTART

Recover before serving.

  1. 01

    Start from the durable checkpoint.

  2. 02

    Replay journal records beyond it.

  3. 03

    Accept connections after recovery.

A clean stop drains in-flight requests and checkpoints the index. After a crash, recover with the previous reactor count before changing the allocation.

Recovery and operating procedures

05 / OPERATING REFERENCE

Know what you’re running.

A self-hosted database with an explicit CPU allocation, resident arenas, and persistent storage on your host.

Host

Linux kernel 6.8+, Docker Compose v2, and ext4 or XFS. Use AVX2-capable x86-64 hardware or ARMv8.2 with Crypto Extensions.

Host requirements

CPU allocation

Set an even physical-core budget from 2 through 1,024. The server derives the reactor count from the actual usable topology, affinity, and CPU quota.

See how cores become reactors
Uniform topology; starting port 7380
Physical coresThreads / coreReactorsPorts
2117380
2227380–7381
8147380–7383
8287380–7387

On mixed CPU sets, complete sibling pairs are used first, then single-threaded cores are paired. Reactor counts can be odd. Shard ranges divide as evenly as possible; the shard count stays fixed at 1,024.

Memory

The automatic arena is 4 GiB for one reactor, or 2 GiB per reactor for multiple reactors. Allow additional process overhead. Explicitly use 4 GiB per reactor for 512 MiB values.

Calculate resident arena RAM

Security

TLS 1.3 protects every client connection. Clients verify the server’s CA-issued Ed25519 identity; mutual TLS can be configured. Values are encrypted at rest, with a passphrase-protected keystore.

Certificates and encryption

Backups

Stop the server or take a filesystem snapshot, then back up the whole data volume, including its keystore. Retain the passphrase securely. A live file copy is not a consistent backup.

Backup and restore guidance

Storage capacity

Provision space beyond live values and plan backups separately. When the volume fills, writes return StorageExhausted; the server continues serving reads.

Disk sizing reference

CHANGING THE ALLOCATION

The owner can change.
The key’s shard stays put.

After a clean stop, change the core budget or starting port, regenerate the port mapping, then restart. The routing epoch advances when ownership or ports change.

  1. 01Stop cleanly
  2. 02Change configuration
  3. 03Configure ports + restart
Follow the configuration procedure
Download the technical reference (.md)

FROM THE ENGINE TO YOUR APPLICATION

Evaluate it with
your workload.

Set up Thunder, verify your first write and read, then test the payloads and concurrency your application needs.