From f7599e79c7f8e70274e63949b3cd9300ba66806a Mon Sep 17 00:00:00 2001
From: "Johan B.W. de Vries" <info@jbwdevries.nl>
Date: Tue, 7 Nov 2023 10:47:19 +0100
Subject: [PATCH] Repo usability fixes

---
 Makefile  |  5 ++++-
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index a231426..82e07ed 100644
--- a/Makefile
+++ b/Makefile
@@ -11,7 +11,10 @@ examples/echoapp.toml: examples/echoserver.toml examples/echoclient.toml
 	cat examples/echoclient.toml >> $@
 
 clickhouse-sh:
-	docker compose exec clickhouse /usr/bin/clickhouse client
+	docker compose exec clickhouse /usr/bin/clickhouse client --database phasm_platform
+
+clickhouse-schema:
+	cat config/clickhouse/schema.sql | docker compose exec -T clickhouse /usr/bin/clickhouse client --multiquery
 
 redis-sh:
 	docker compose exec -it redis redis-cli
diff --git a/README.md b/README.md
index c046fbd..8610588 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,61 @@
 # phasm-platform
 
-## Steps
+## Background
+
+[phasm](https://git.jbwdevries.nl/jbwdevries/phasm) is a language that compiles
+to WebAssembly. This platform can run compiled phasm code, with every module
+running as a container or as a service. Modules can call other modules, if they
+are registered as a service.
+
+Think of it as Kubernetes, but except that every container is an OS, it's a
+program.
+
+## Terminology
+
+A phasm cluster consists of controllers and workers. The controller manage the
+workers. The workers run the modules.
+
+A worker can run in standalone mode. In that case, control functionality is
+limited, but for basic use cases, it will suffice.
+
+Logging is done via ClickHouse. Modules can log directly, but the platform also
+logs routed calls from one module to another.
+
+Controllers manage their state using redis.
+
+## Status
+
+This project is build in lockstep with the phasm compiler.
+
+The controller is not implemented at all yet.
+
+The worker can currently run the examples that you see in the `examples/`
+directory. These first need to be compiled from the .py files to .wasm files
+using the phasm compiler.
+
+## Running the worker
 ```sh
+# Setup the virtuel environment
 make setup
+
+# Run the dependent services using docker compose
 make init
-make run-controller
-```
\ No newline at end of file
+
+# Import the schema for the logging
+make clickhouse-schema
+
+# Launch the worker. This won't output much.
+# Press Ctrl+C when you're done running the processes.
+make run-worker
+
+# Run the ClickHouse CLI to get access to the logs
+make clickhouse-sh
+```
+
+```sql
+-- See the direct logging output from modules
+SELECT * FROM container_logs ORDER BY timestamp;
+
+-- See the routing logs between services
+SELECT * FROM routing_logs ORDER BY timestamp;
+```