docs: clean up architecture guide

Author: erikgrinaker

README.md

@@ -2,9 +2,9 @@
 
 Distributed SQL database in Rust, built from scratch as an educational project. Main features:
 
-* [Raft distributed consensus engine][raft] for linearizable state machine replication.
+* [Raft distributed consensus][raft] for linearizable state machine replication.
 
-* [ACID transaction engine][txn] with MVCC-based snapshot isolation.
+* [ACID transactions][txn] with MVCC-based snapshot isolation.
 
 * [Pluggable storage engine][storage] with [BitCask][bitcask] and [in-memory][memory] backends.
 
@@ -31,17 +31,17 @@ been taken where possible.
 [memory]: https://github.com/erikgrinaker/toydb/blob/main/src/storage/memory.rs
 [query]: https://github.com/erikgrinaker/toydb/blob/main/src/sql/execution/executor.rs
 [optimizer]: https://github.com/erikgrinaker/toydb/blob/main/src/sql/planner/optimizer.rs
-[sql]: https://github.com/erikgrinaker/toydb/blob/main/src/sql/mod.rs
+[sql]: https://github.com/erikgrinaker/toydb/blob/main/src/sql/parser.rs
 
 ## Documentation
 
 * [Architecture guide](docs/architecture/index.md): a guided tour of toyDB's code and architecture.
 
 * [SQL examples](docs/examples.md): walkthrough of toyDB's SQL features.
 
-* [SQL reference](docs/sql.md): toyDB's SQL reference documentation.
+* [SQL reference](docs/sql.md): reference documentation for toyDB's SQL dialect.
 
-* [References](docs/references.md): research material used while building toyDB.
+* [References](docs/references.md): research materials used while building toyDB.
 
 ## Usage
 
@@ -161,9 +161,10 @@ The available workloads are:
 
 For more information about workloads and parameters, run `cargo run --bin workload -- --help`.
 
-Example workload results are listed below. Write performance is pretty atrocious, due to fsyncs 
-and a lack of write batching at the Raft level. Disabling fsyncs, or using the in-memory engine, 
-significantly improves write performance.
+Example workload results are listed below. Write performance is atrocious, due to
+[fsync](https://en.wikipedia.org/wiki/Sync_(Unix)) and a lack of write batching in the Raft layer.
+Disabling fsync, or using the in-memory engine, significantly improves write performance (at the
+expense of durability).
 
 | Workload | BitCask     | BitCask w/o fsync | Memory      |
 |----------|-------------|-------------------|-------------|
@@ -181,4 +182,4 @@ library 'toydb'".
 
 ## Credits
 
-toyDB logo is courtesy of [@jonasmerlin](https://github.com/jonasmerlin).
+The toyDB logo is courtesy of [@jonasmerlin](https://github.com/jonasmerlin).

docs/architecture/encoding.md

@@ -1,7 +1,7 @@
 # Key/Value Encoding
 
 The key/value store uses binary `Vec<u8>` keys and values, so we need an encoding scheme to 
-translate between Rust in-memory data structures and the on-disk binary data. This is provided by
+translate between in-memory Rust data structures and the on-disk binary data. This is provided by
 the [`encoding`](https://github.com/erikgrinaker/toydb/tree/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/encoding)
 module, with separate schemes for key and value encoding.
 
@@ -15,18 +15,19 @@ data type. But we could also have chosen e.g. [JSON](https://en.wikipedia.org/wi
 We won't dwell on the actual binary format here, see the [Bincode specification](https://github.com/bincode-org/bincode/blob/trunk/docs/spec.md)
 for details.
 
-To use a consistent configuration for all encoding and decoding, we provide helper functions using
-`bincode::config::standard()` in the [`encoding::bincode`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/encoding/bincode.rs)
-module:
+To use a consistent configuration for all encoding and decoding, we provide helper functions in
+the [`encoding::bincode`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/encoding/bincode.rs)
+module which use `bincode::config::standard()`.
 
 https://github.com/erikgrinaker/toydb/blob/0ce1fb34349fda043cb9905135f103bceb4395b4/src/encoding/bincode.rs#L15-L27
 
-Bincode uses the very common [Serde](https://serde.rs) framework for its API. toyDB also provides
-an `encoding::Value` helper trait for value types with automatic `encode()` and `decode()` methods:
+Bincode uses the very common [Serde](https://serde.rs) framework for its API. toyDB also provides an
+`encoding::Value` helper trait for value types which adds automatic `encode()` and `decode()`
+methods:
 
 https://github.com/erikgrinaker/toydb/blob/b57ae6502e93ea06df00d94946a7304b7d60b977/src/encoding/mod.rs#L39-L68
 
-Here's an example of how this is used to encode and decode an arbitrary `Dog` data type:
+Here's an example of how this can be used to encode and decode an arbitrary `Dog` data type:
 
 ```rust
 #[derive(serde::Serialize, serde::Deserialize)]
@@ -42,7 +43,7 @@ let pluto = Dog { name: "Pluto".into(), age: 4, good_boy: true };
 let bytes = pluto.encode();
 println!("{bytes:02x?}");
 
-// Outputs [05, 50, 6c, 75, 74, 6f, 04, 01].
+// Outputs [05, 50, 6c, 75, 74, 6f, 04, 01]:
 //
 // * Length of string "Pluto": 05.
 // * String "Pluto": 50 6c 75 74 6f.
@@ -54,37 +55,37 @@ let pluto = Dog::decode(&bytes)?; // gives us back Pluto
 
 ## `Keycode` Key Encoding
 
-Unlike values, keys can't just use any binary encoding like Bincode. As mentioned before, the
-storage engine sorts data by key to enable range scans, which will be used e.g. for SQL table scans,
-limited SQL index scans, Raft log scans, etc. Because of this, the encoding needs to preserve the
-[lexicographical order](https://en.wikipedia.org/wiki/Lexicographic_order) of the encoded values:
-the binary byte slices must sort in the same order as the original values.
+Unlike values, keys can't just use any binary encoding like Bincode. As mentioned in the storage
+section, the storage engine sorts data by key to enable range scans. The key encoding must therefore
+preserve the [lexicographical order](https://en.wikipedia.org/wiki/Lexicographic_order) of the
+encoded values: the binary byte slices must sort in the same order as the original values.
 
-As an example of why we can't just use Bincode, let's consider two strings: "house" should be
-sorted before "key", alphabetically. However, Bincode encodes strings prefixed by their length, so
-"key" would be sorted before "house" in binary form:
+As an example of why we can't just use Bincode, consider the strings "house" and "key". These should
+be sorted in alphabetical order: "house" before "key". However, Bincode encodes strings prefixed by
+their length, so "key" would be sorted before "house" in binary form:
 
 ```
-03 6b 65 79       ← 3 bytes: key
-05 68 6f 75 73 65 ← 5 bytes: house
+03 6b 65 79        ← 3 bytes: key
+05 68 6f 75 73 65  ← 5 bytes: house
 ```
 
-For similar reasons, we can't just encode numbers in their native binary form, because the
-[little-endian](https://en.wikipedia.org/wiki/Endianness) representation will sometimes order very
-large numbers before small numbers, and the [sign bit](https://en.wikipedia.org/wiki/Sign_bit)
-will order positive numbers before negative numbers.
+For similar reasons, we can't just encode numbers in their native binary form: the
+[little-endian](https://en.wikipedia.org/wiki/Endianness) representation will order very large
+numbers before small numbers, and the [sign bit](https://en.wikipedia.org/wiki/Sign_bit) will order
+positive numbers before negative numbers. This would violate the ordering of natural numbers.
 
 We also have to be careful with value sequences, which should be ordered element-wise. For example,
 the pair ("a", "xyz") should be ordered before ("ab", "cd"), so we can't just encode the strings
-one after the other like "axyz" and "abcd" since that would sort "abcd" first.
+one after the other like "axyz" and "abcd" since that would sort ("ab", "cd") first.
 
-toyDB provides an encoding called "Keycode" which provides these properties, in the
-[`encoding::keycode`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/encoding/keycode.rs)
-module. It is implemented as a [Serde](https://serde.rs) (de)serializer, which
-requires a lot of boilerplate code, but we'll just focus on the actual encoding.
+toyDB provides an order-preserving encoding called "Keycode" in the [`encoding::keycode`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/encoding/keycode.rs)
+module. Like Bincode, the Keycode encoding is not self-describing: the binary data does not say what
+the data type is, the caller must provide a type to decode into. It only supports a handful of
+primitive data types, and only needs to order values of the same type.
 
-Keycode only supports a handful of primary data types, and just needs to order values of the same
-type:
+Keycode is implemented as a [Serde](https://serde.rs) (de)serializer, which requires a lot of
+boilerplate code to satisfy the trait, but we'll just focus on the actual encoding. The encoding
+scheme is as follows:
 
 * `bool`: `00` for `false` and `01` for `true`.
 
@@ -113,22 +114,20 @@ type:
 
     https://github.com/erikgrinaker/toydb/blob/2027641004989355c2162bbd9eeefcc991d6b29b/src/encoding/keycode.rs#L185-L188
 
-* `Vec<T>`, `[T]`, `(T,)`: just the concatenation of the inner values.
+* `Vec<T>`, `[T]`, `(T,)`: the concatenation of the inner values.
 
     https://github.com/erikgrinaker/toydb/blob/2027641004989355c2162bbd9eeefcc991d6b29b/src/encoding/keycode.rs#L295-L307
 
-* `enum`: the enum variant's numerical index as a `u8`, then the inner values (if any).
+* `enum`: the variant's numerical index as a `u8`, then the inner values (if any).
 
     https://github.com/erikgrinaker/toydb/blob/2027641004989355c2162bbd9eeefcc991d6b29b/src/encoding/keycode.rs#L223-L227
 
-Decoding is just the inverse of the encoding.
-
 Like `encoding::Value`, there is also an `encoding::Key` helper trait:
 
 https://github.com/erikgrinaker/toydb/blob/b57ae6502e93ea06df00d94946a7304b7d60b977/src/encoding/mod.rs#L20-L37
 
-We typically use enums to represent different kinds of keys. For example, if we wanted to store
-cars and video games, we could use:
+Different kinds of keys are usually represented as enums. For example, if we wanted to store cars
+and video games, we could use:
 
 ```rust
 #[derive(serde::Serialize, serde::Deserialize)]