docs/architecture: split out client section

erikgrinaker · erikgrinaker · commit 63abefd62832 · 2025-05-11T15:13:43.000+02:00
diff --git a/docs/architecture/client.md b/docs/architecture/client.md
@@ -0,0 +1,62 @@
+# Client
+
+The toyDB client is in the [`client`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs)
+module. It uses the same Bincode-based protocol that we saw in the server section, sending
+`toydb::Request` and receiving `toydb::Response`.
+
+## Client Library
+
+The main client library `toydb::Client` is used to connect to a toyDB server:
+
+https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L15-L24
+
+When initialized, it connects to a toyDB server over TCP:
+
+https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L27-L33
+
+It can then send Bincode-encoded `toydb::Request` to the server, and receive `toydb::Response`
+back.
+
+https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L35-L40
+
+
+In particular, `Client::execute` can be used to execute arbitrary SQL statements in the client's
+current session:
+
+https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L42-L56
+
+## `toysql` Binary
+
+However, `toydb::Client` is a programmatic API, and we want a more convenient user interface.
+The `toysql` client in [`src/bin/toysql.rs`](https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs)
+provides a typical [REPL](https://en.wikipedia.org/wiki/Read–eval–print_loop) (read-evaluate-print loop) where users can enter SQL statements and view the results.
+
+Like `toydb`, `toysql` is a tiny [`clap`](https://docs.rs/clap/latest/clap/) command that takes a
+toyDB server address to connect to and starts an interactive shell:
+
+https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L29-L53
+
+This first attempts to connect to the toyDB server using the `toydb::Client` client, and then starts
+an interactive shell using the [Rustyline](https://docs.rs/rustyline/latest/rustyline/) library.
+
+https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L55-L81
+
+The shell is simply a loop that prompts the user to input a SQL statement:
+
+https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L216-L250
+
+Each statement is the executed against the server via `toydb::Client::execute`, and the response
+is formatted and printed as output:
+
+https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L83-L92
+
+https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L175-L204
+
+And with that, we have a fully functional SQL database system and can run queries to our heart's
+content. Have fun!
+
+---
+
+<p align="center">
+← <a href="server.md">Server</a>
+</p>
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
@@ -56,13 +56,13 @@ to the actual source code.
   * [Execution](sql-execution.md)
     * [Plan Executor](sql-execution.md#plan-executor)
     * [Session Management](sql-execution.md#session-management)
-* [Server and Client](server.md)
-  * [Server](server.md#server)
+* [Server](server.md)
   * [Raft Routing](server.md#raft-routing)
   * [SQL Service](server.md#sql-service)
   * [`toydb` Binary](server.md#toydb-binary)
-  * [Client Library](server.md#client-library)
-  * [`toysql` Binary](server.md#toysql-binary)
+* [Client](client.md)
+  * [Client Library](client.md#client-library)
+  * [`toysql` Binary](client.md#toysql-binary)
 
 ---
 
diff --git a/docs/architecture/server.md b/docs/architecture/server.md
@@ -1,11 +1,6 @@
 # Server and Client
 
-Now that we've gone over the individual components, we'll tie them all together with the server and
-client.
-
-## Server
-
-in the toyDB
+Now that we've gone over the individual components, we'll tie them all together in the toyDB
 server `toydb::Server`, located in the [`server`](https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs) module.
 
 The server wraps an inner Raft node `raft::Node`, which manages the SQL state machine, and is
@@ -113,60 +108,8 @@ https://github.com/erikgrinaker/toydb/blob/8f8eae0dcf70b1a0df2e853b1f6600e0c7075
 
 toyDB is now up and running!
 
-## Client Library
-
-The main client library `toydb::Client` in the [`client`](https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs)
-module is used to connect to a toyDB server:
-
-https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L15-L24
-
-When initialized, it connects to a toyDB server over TCP:
-
-https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L27-L33
-
-It can then send Bincode-encoded `toydb::Request` to the server, and receives `toydb::Response`
-back.
-
-https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L35-L40
-
-
-In particular, `Client::execute` can be used to execute arbitrary SQL statements in the client's
-session:
-
-https://github.com/erikgrinaker/toydb/blob/213e5c02b09f1a3cac6a8bbd0a81773462f367f5/src/client.rs#L42-L56
-
-## `toysql` Binary
-
-However, `toydb::Client` is a programmatic API, and we want a more convenient user interface.
-The `toysql` client in [`src/bin/toysql.rs`](https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs)
-provides a typical [REPL](https://en.wikipedia.org/wiki/Read–eval–print_loop) (read-evaluate-print loop) where users can enter SQL statements and view the results.
-
-Like `toydb`, `toysql` is a tiny [`clap`](https://docs.rs/clap/latest/clap/) command that takes a
-toyDB server address to connect to and starts an interactive shell:
-
-https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L29-L53
-
-This first attempts to connect to the toyDB server using the `toydb::Client` client, and then starts
-an interactive shell using the [Rustyline](https://docs.rs/rustyline/latest/rustyline/) library.
-
-https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L55-L81
-
-The shell is simply a loop that prompts the user to input a SQL statement:
-
-https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L216-L250
-
-Each statement is the executed against the server via `toydb::Client::execute`, and the response
-is formatted and printed as output:
-
-https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L83-L92
-
-https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/bin/toysql.rs#L175-L204
-
-And with that, we have a fully functional SQL database system and can run queries to our heart's
-content. Have fun!
-
 ---
 
 <p align="center">
-← <a href="sql-execution.md">SQL Execution</a>
+← <a href="sql-execution.md">SQL Execution</a> &nbsp; | &nbsp; <a href="client.md">Client</a> →
 </p>
diff --git a/docs/architecture/sql-execution.md b/docs/architecture/sql-execution.md
@@ -115,5 +115,5 @@ And with that, we have a fully functional SQL engine!
 ---
 
 <p align="center">
-← <a href="sql-optimizer.md">SQL Optimization</a> &nbsp; | &nbsp; <a href="server.md">Server and Client</a> →
+← <a href="sql-optimizer.md">SQL Optimization</a> &nbsp; | &nbsp; <a href="server.md">Server</a> →
 </p>
