Dear Sean, thank you for usermanager-example.
In trying to understand your code, I re-read the chapter "Def, Symbols, and Vars" in the book "Getting Clojure". Then I did the following repl experiment:

user=> (def f (fn [x] (* x x)))
#'user/f
user=> (def g #'f)
#'user/g
user=> (g 2)
4
user=> (def h f)
#'user/h
user=> (h 2)
4

So,(g 2) and (h 2) being the same, I changed #'my-middleware to my-middleware in your code. The result is, that usermanager-example seems to work flawlessly.

I tried another repl experiment:

user=> (def a 1)
#'user/a
user=> (def b #'a)
#'user/b
user=> b
#'user/a
user=> (def c a)
#'user/c
user=> c
1

From this, I understand that sometimes it might be useful to pass the variable #'a instad of the bound value 1 in some function call. It is useful, because the symbol a is bound to a number and not to a (fn ...). But, as I tried to explain above, if some symbol f is bound to a (fn ...), I do not understand the use of passing the var #'f instead of the (fn ...) bound to f.

So, to rephrase my question: did you write this #'my-middleware instead of just my-middleware only because it is "more correct" in some sense, because it is more idiomatic, because it is better style? Or is it necessary for some reason?

I hope that you found the patience to bear with my problem and read to this end, and I ask for your answer in the hope to understand usermanager-example a bit better.

Drop all the http-kit stuff (it just confuses folks). Maybe leave comments in about what would be needed to switch from Jetty to http-kit?

Either drop the promise or explain its purpose better? Probably simpler to just drop it.

Ensure started server component is written to a REPL-friendly Var and explain that as well.

The idea is to make the example more turnkey, so folks don't need an XTDB instance running to use the app.

The 'server' parameter of WebServer in usermanager.main is unused.

Looks like the "polylith" branch suggests running:

clj -M:dev -m usermanager.web.main

but a newbie like myself cloned the repo and immediately was put onto the "develop" branch where you have to run:

clj -M:dev -m usermanager.main

This might be a very small detail but probably everyone trips over this when trying this cool project out for the first time. I see you even say to run using the "polylith" branch but it's a little buried.

IMHO make those two branches align so everyone doesn't have to figure that out.

Very cool project example though, thanks @seancorfield !

In particular, workspace.edn should update :vcs and :tag-patterns.

It might be more idiomatic to have the example use XTQL instead of SQL.

The original thinking was that keeping the SQL so similar to the main example meant fewer things needed to change -- but the qualified/unqualified column name stuff kind of sank that minimalism. So the question is whether it would be worth switching the example to XTQL (in which case we could keep the qualified names, aside from using xt/id instead of <table>/id).

Step 0: successful initialisation of application

With original code unchanged, in the repl I evaluated the following two forms:

(def system (new-system 8888))
(alter-var-root #'system component/start)

Then, I modified the route handlers in the function my-handler. After doing a top-level evaluation of my-handler, the application did still not reflect the changes.

Unsuccessful activation of new handlers

After Step 0, I evaluated two forms:

(alter-var-root #'system component/stop)
(alter-var-root #'system component/start)

As opposed to my expectation, the function start in the WebServer record was not called, whereas this function start was indeed called upon Step 0 (see screenshot, note the expected but missing message "in record WebServer: start" after the last line). Naturally enough, the application showed a "localhost refused to connect." error.

Successful activation of new handlers

After Step 0, I evaluated three forms:

(alter-var-root #'system component/stop)
(def system (new-system 8888))
(alter-var-root #'system component/start)

Is this is the right way to activate the modified handlers? It seems odd to create another system for that.