add ui

README.md

@@ -1,17 +1,19 @@
 # tbd
 
 A small Clojure HTTP API built on [Ring](https://github.com/ring-clojure/ring) (Jetty) and
-[reitit](https://github.com/metosin/reitit), with Swagger UI docs, unit tests, dockerized
-integration tests, and joint line coverage.
+[reitit](https://github.com/metosin/reitit), with a ClojureScript
+[re-frame](https://github.com/day8/re-frame) front end (`ui/`), Swagger UI docs, unit tests,
+dockerized integration tests, and joint line coverage.
 
 ## Requirements
 
 - Docker, for the integration tests and the `script/docker-*` tasks (all CI needs)
-- For running tasks natively (optional): [Clojure CLI](https://clojure.org/guides/install_clojure) (tools.deps) with JDK 11+, and [Babashka](https://babashka.org/) for `script/coverage-report`
+- For running tasks natively (optional): [Clojure CLI](https://clojure.org/guides/install_clojure) (tools.deps) with JDK 11+, [Node](https://nodejs.org/) 20+ (with a JDK) for the UI build, and [Babashka](https://babashka.org/) for `script/coverage-report`
 
 ## Running
 
 ```bash
+script/ui-build        # compile the UI (once, and after UI changes)
 script/server [port]
 ```
 
@@ -23,7 +25,9 @@ script/server 8080
 PORT=8080 script/server
 ```
 
-This is a thin wrapper around `clojure -X:run`, which also honors `PORT`.
+This is a thin wrapper around `clojure -X:run`, which also honors `PORT`. Then open
+http://localhost:3000 for the UI. Without `script/ui-build` the server still starts, but `/`
+shows a placeholder.
 
 Or build and run the container:
 
@@ -36,7 +40,7 @@ docker run --rm -p 3000:3000 tbd
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/` | Plain-text landing message |
+| `GET` | `/` | The UI: an HTML shell that loads the compiled ClojureScript from `/js/main.js` |
 | `GET` | `/api/ping` | Health check, returns `pong` |
 | `GET` | `/api/add?x=2&y=3` | Adds two numbers, returns EDN: `{:result 5}` (400 if either is missing or not a number) |
 | `GET` | `/api-docs` | Swagger UI |
@@ -47,6 +51,23 @@ curl localhost:3000/api/ping           # pong
 curl 'localhost:3000/api/add?x=2&y=3'  # {:result 5}
 ```
 
+## UI
+
+`ui/` is a [re-frame](https://github.com/day8/re-frame) app (ClojureScript, React 19 via
+[Reagent](https://reagent-project.github.io/)) built with [shadow-cljs](https://github.com/thheller/shadow-cljs).
+It's a small calculator form that calls `GET /api/add` and shows the sum (or the server's
+validation error).
+
+shadow-cljs compiles it into `resources/public/js/` (git-ignored). The server serves that
+directory at `/js`, and serves `resources/public/index.html`, the shell that mounts the app, at `/`.
+
+| Task | What it does |
+|------|--------------|
+| `script/ui-build` | Optimized release build into `resources/public/js` |
+| `script/ui-watch` | Rebuilds on every change, with hot reload; run `script/server` alongside and refresh the page |
+
+The Docker image builds the UI in its own stage, so `docker build` needs no local Node.
+
 ## Development
 
 Every task is a bash script in `script/`. Start an nREPL server (with CIDER middleware) on the port in `.nrepl-port`, or `3000` if that
@@ -88,9 +109,11 @@ src/tbd/
   core.clj            Router, Ring app, and server startup
   <group>/routes.clj  Each route group (health, math, ...) owns its route subtree
   <group>/core.clj    Business logic for the group, with no HTTP concerns
+ui/                   ClojureScript re-frame app (shadow-cljs project); ui/src/tbd/ui/{db,events,subs,views,core}.cljs
+resources/public/     index.html (the shell served at /) and js/ (compiled UI output, git-ignored)
 test/                 Unit tests
 integration-test/     Dockerized integration tests and coverage harness
-script/               Bash entry points (test, coverage, repl, ...) and coverage helpers
+script/               Bash entry points (server, ui-build, test, coverage, repl, ...) and coverage helpers
 ```
 
 To add a new group, create `tbd.<group>.routes` with a `routes` fn that returns a reitit route