Front End

Decisions

I'm not a fan of front ends that run as JavaScript in a browser. I just don't get it. Why? For example, Java has a fully competent installation mechanism for applications. So does Windows. There are cross-platform equivalents. There is no good reason to use Javascript in a browser unless the best Front End tool is in fact one that is only browser based. Therefore, I switched it into plan mode and prompted the LLM:

I am rethinking what I wrote in @src/dockb/services/README.md#L25:
"The API (FastAPI) will be responding to change events which come from the FE and originate from Lexical,"
because I am not sure I want to use a browser-based front end.
Research the internet to see if there are alternative libraries (in any language) which provide similar editing ability.
(What I really need, is an editor which allows me to easily create events in the front end in response to user edits and keystrokes
which relate back to the semantic model relative to document, chapter, paragraph, sentence objects. The modesl contain methods
for deleting children and inserting new children relative to existing ones. The FE will need to be able to call the BE in such a
way that it can refer to the original elements before the edit. Therefore, the FE must be able to keep the relationship between the
textual characters, and the semantic models: document, chapter, paragraph and sentence. It does not need to go as far as keeping
track of tokens, and in fact that would be going too far, and would not be useful.
Find alternatives to Lexical, which will work as well or better, but not require a browser, and any language..
Note: It is a HARD REQUIREMENT to not have to implement messy and fragile logic that maps character positions to models.
The library itself must maintain that for me.

It came up with two options: prosemirror-rs (Rust), and pycrdt (Python, CRDT bindings for Yrs/Rust).
I told it to explore prosemirror first.

It suggested prosemirror-py for a Textual TUI FE to prove the concept, or prosemirror-rs for a full egui/iced FE.

I quite like the idea of a TUI, not just as a starting point, but as a simple UI for terminal-only. I told it to plan that out. This is a pre-design LLM-assisted brainstorming step. I am not letting it write code yet. I need to consider how the REST API will work also, before starting an actual design. I told it to suggest an API.

It came up with a pretty good API, which I told it to write as a markdown file. You can see the original version here as created by Big Pickle . The first thing I noticed is that a Document does not have a name. Obviously a document will have many attributes. It is obviously incomplete. I then edited the API design heavily, to the final version of here:

src/dockb/controllers/README_API.md .

Now I'd like to be able to say that the re-work of README_API.md was my work, but it was not. I did some fairly large restructuring of the design, but then I asked Big Pickle to analyse the design as so:

I have changed the design which was expressed in a few of the README*.md files in the @src/** directory hierarchy.
Previously all requests were to come in as events. Now there are individual POST and PUT requests for controllers
corresponding to Document, Chapter, Paragraph, and Sentence. Check current design, especially what is expressed in
@src/dockb/infrastructure/neo4j/README.md @src/dockb/services/README.md and @src/dockb/controllers/README_API.md -
make sure it will be able to naturally handle events that originate in ProseMirror and call POST/PUT requests to get
the models changed in the BE. Does it cover everything? Will it be awkward, or will it be fairly natural?
Can you suggest improvements?

It found 4 gaps, one quite serious. I allowed it to fix all 4 with some input from me. Then I repeated the last part of my previous prompt, and it found some more issues...

The LLM was extremely useful in honing this design. You have to be nuts not to take advantage of this new tech...

I went on to get the LLM to create a bunch of skeletons of classes for session management, login, and auth. I also got it to write some failing tests for the SessionContext class, and then stepped back to look again at README_API.md, and to hone down the session management design.

Admittedly there is a lot going on between me and the LLM which I'm not documenting here, but now that the LLM has more context (the emerging code base), it is making much better decisions, and I can trust it more. This LLM is not from Anthropic, and OpenCode is not Claude, so you can probably take my cautions in this blog, and tone them down a bit, when applying the same approach to working with an AI if the tool is Claude. Basically: use TDD and work with the LLM, instruct it, drive it, and enjoy the process.

I think I've said enough about this process, and will get on with finishing my project.