From e84e9e659455ee708aad7f5934d57d31d6e98783 Mon Sep 17 00:00:00 2001
From: "D. Scott Boggs" <scott@tams.tech>
Date: Sun, 25 Jun 2023 11:30:45 -0400
Subject: [PATCH] Add README

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1282a0e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# Kalkutago
+
+A multi-user Tickmate clone for the web
+
+## Development
+### Before you start
+The backend uses a postgres server which is not tracked as a part of the
+repository, and neither is the password for it. You'll need to generate a
+password by doing something like
+
+```console
+openssl rand -base64 36 > server/postgres.pw
+```
+
+The development environment uses Traefik to reverse-proxy the API and dev
+server. In production, the API will serve the client directly, but this system
+allows you to run the dev server behind a reverse proxy so that changes are
+rendered quickly without having to rebuild the container. Using the vite dev
+server also gets us better debugging in the browser. 
+
+However, that means that Traefik needs a hostname to listen for. The way I've
+done this is by adding the following entry to my `/etc/hosts` file:
+
+```
+127.0.0.1 kalkutago
+```
+
+### Server
+The server is written in Rust, using Rocket and SeaOrm. It uses Rust nightly, so
+you'll need to `rustup override set nightly`, though it gets built in docker so
+you really only need this for IDE support.
+
+### Client
+
+The client is a Vue application. It has a central state in
+[`state.ts`](client/src/state.ts). On application load, the state is initialized
+by fetching the current tracks and ticks via the API, and then subscribes to
+updates from the server by opening an EventSource at `/api/v1/updates`.
+
+The basic flow is:
+ - a user interaction happens which should trigger a state change
+ - the action is dispatched to the server (e.g. by making a PATCH request to
+   `/api/v1/tracks/<track_id>/ticked`)
+ - the server makes the appropriate change to the database
+ - an event is dispatched to the event sources subscribed via `/api/v1/updates`
+ - The client receives the event, the reactive state is updated, and the UI
+   changes to match the expected state.
+
+### Running for development
+
+`docker-compose_dev.yml` is symlinked to `docker-compose.yml` for now, so once
+the hostname is set up Just run `docker-compose up --build` and visit
+http://kalkutago/ to open the app
+
+### Populating the database
+In order to see the UI components I add a track to the database like
+
+```console
+curl --json '{"name": "test", "description": "test track", "icon": "❓", "enabled": 1}' kalkutago/api/v1/tracks
+```
\ No newline at end of file