docs: reword documentation; provide more details on compartmentalization

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I21494f1b5a2256c12aa4496a9ea7de8f6a6a6964

README.md

@@ -7,57 +7,83 @@ collections, and audit logging. It supports both SQLite and PostgreSQL backends.
 
 ## Building
 
-```sh
+```bash
 # Build all compilable crates
-cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
+$ cargo build -p pinakes-core -p pinakes-server -p pinakes-tui
 
 # The Dioxus UI requires GTK3 and libsoup system libraries:
 # On Debian/Ubuntu: apt install libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev
 # On Fedora: dnf install gtk3-devel libsoup3-devel webkit2gtk4.1-devel
 # On Nix: Use the dev shell, everything is provided :)
-cargo build -p pinakes-ui
+$ cargo build -p pinakes-ui
+
+# Alternatively, while app deps are in PATH, you may simply build the entire
+# workspace.
+$ cargo build --workspace
 ```
 
 ## Configuration
 
-Copy the example config and edit it:
+Pinakes runs with its own built-in configuration file out of the box. While
+using the default configuration, you will not be able to edit the configuration
+but it will provide the minimum required configuration values to get you going
+with Pinakes. If you are more interested in fully configuring Pinales, you must
+create your own configuration. You may copy the example config and edit it to
+your needs:
 
-```sh
-cp pinakes.toml.example pinakes.toml
+```bash
+# Copy the sample config
+$ cp pinakes.toml.example pinakes.toml
 ```
 
 Key settings:
 
-- `storage.backend` -- `"sqlite"` or `"postgres"`
-- `storage.sqlite.path` -- Path to the SQLite database file
-- `storage.postgres.*` -- PostgreSQL connection parameters
-- `directories.roots` -- Directories to scan for media files
-- `scanning.watch` -- Enable filesystem watching for automatic imports
-- `scanning.ignore_patterns` -- Patterns to skip during scanning (e.g., `".*"`,
+- `storage.backend` - `"sqlite"` or `"postgres"`
+- `storage.sqlite.path` - Path to the SQLite database file
+- `storage.postgres.*` - PostgreSQL connection parameters
+- `directories.roots` - Directories to scan for media files
+- `scanning.watch` - Enable filesystem watching for automatic imports
+- `scanning.ignore_patterns` - Patterns to skip during scanning (e.g., `".*"`,
   `"node_modules"`)
-- `server.host` / `server.port` -- Server bind address
+- `server.host` / `server.port` - Server bind address
 
 ## Running
 
 ### Server
 
+To use Pinakes, you will need the server to be running. The GUI on its own will
+work, but it will not be functional without the server.
+
 ```sh
-cargo run -p pinakes-server -- pinakes.toml
-# or
-cargo run -p pinakes-server -- --config pinakes.toml
+# Start the server first
+$ cargo run -p pinakes-server -- pinakes.toml
+
+# or:
+$ cargo run -p pinakes-server -- --config pinakes.toml
 ```
 
-The server starts on the configured host:port (default `127.0.0.1:3000`).
+The server starts on the configured host:port (default `127.0.0.1:3000`). In a
+production scenario you are encouraged to reverse proxy the service, and prefer
+SSL.
 
 ### TUI
 
-```sh
-cargo run -p pinakes-tui
+The Pinakes TUI can be used to manage your collections from the comfort of your
+terminal. While the server is running you may connect to it using the `--server`
+flag.
+
+```bash
+# Using defaults
+$ cargo run -p pinakes-tui
+
 # or with a custom server URL:
-cargo run -p pinakes-tui -- --server http://localhost:3000
+$ cargo run -p pinakes-tui -- --server http://localhost:3000
 ```
 
-Keybindings:
+#### Keybindings
+
+The TUI component of Pinakes is designed to be keyboard-centric, as it is
+designed for the terminal. The keybindings are as follows:
 
 <!-- markdownlint-disable MD013-->
 
@@ -86,16 +112,24 @@ Keybindings:
 
 ### Desktop/Web UI
 
-```sh
-cargo run -p pinakes-ui
+Pinakes features a fully fledged Desktop and Web UI powered by Dioxus. Those two
+components are meant as a GUI frontend for the Pinakes server, and are
+interchangeable in terms of usage.
+
+```bash
+# Build the UI
+$ cargo run -p pinakes-ui
 ```
 
-Set `PINAKES_SERVER_URL` to point at the server if it is not on
-`localhost:3000`.
+> [!TIP]
+> By default Pinakes GUI will assume the server to be running on localhost and
+> bound to port 3000. Set `PINAKES_SERVER_URL` to point at the server if it is
+> not on `localhost:3000`.
 
 ## API
 
-All endpoints are under `/api/v1`.
+There exists a comprehensive UI for the server component that you may query
+directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`.
 
 ### Media
 
@@ -185,9 +219,17 @@ Metadata extraction uses lofty (audio, MP4), matroska (MKV), lopdf (PDF), epub
 
 ## Storage Backends
 
-**SQLite** (default) -- Single-file database with WAL mode and FTS5 full-text
-search. Bundled SQLite guarantees FTS5 availability.
+Two storage backends are supported. For convenience, SQLite is the default
+backend out of the box but for production deployments you may choose to prefer
+PostgreSQL.
 
-**PostgreSQL** -- Native async with connection pooling (deadpool-postgres). Uses
-tsvector with weighted columns for full-text search and pg_trgm for fuzzy
-matching. Requires the `pg_trgm` extension.
+### **SQLite** (default)
+
+Single-file database with WAL mode and FTS5 full-text search. Bundled SQLite
+guarantees FTS5 availability.
+
+### **PostgreSQL**
+
+Native async with connection pooling (deadpool-postgres). Uses tsvector with
+weighted columns for full-text search and pg_trgm for fuzzy matching. Requires
+the `pg_trgm` extension.