Kittehlist docu(te)mentation

kittehlist is a todo list for kittehs (and other beings) currently in early development. kittehlist is a web application which allows you to create checklists, such as for to-do’s, groceries, or anything else that you want to keep track of in such a list. kittehlist is end-to-end encrypted, so only the people you share a list with can read that list’s content. kittehlist features realtime collaboration, and changes to the list are immediately visible to anyone looking at the list. kittehlist is effectively an upgrade and rewrite of kaufkauflist, with the intention of sunsetting kaufkauflist and its public deployment once kittehlist is a viable replacement.

This is kittehlist’s documentation (cute), for users, developers, and admins. It will eventually be publicly served so that kittehlist instances can link to it.

The documentation, just like kittehlist, is WIP. Some design details are not decided yet and are being fleshed out as development on the core featureset progresses. Basic information can be found at the project’s README.

The documentation has two sections:

• The user documentation will contain a manual for end users. This section has not been written yet, but will be directly linked from various places in the webapp itself, as the webapp won’t contain extensive documentation.
• The technical documentation will contain technical docs for developers, administrators, and others interested in kittehlist’s inner workings. Since the code itself contains detailed documentation, the technical docs will focus on higher-level descriptions of architecture, REST API, and cryptography. If you want to write a third-party compatible frontend or backend for kittehlist, or if you want to review or audit the cryptography, this section is suitable.

FAQ

Why is there so much frontend code? Why doesn’t kittehlist work without JavaScript?

kittehlist provides end-to-end encryption. Rendering the list on the server and sending that to the browser would defeat the whole point of kittehlist.

Why not use…

TypeScript/JavaScript with React/Angular/[insert framework here] for the frontend?

We are not web developers and we don’t like these frameworks. They make the page load slower due to both script sizes and JavaScript’s speed, and they require you to structure your application to fit the framework, often reducing accessibility by default. Even though Rust needs to go through the Wasm-JavaScript interface twice for every single web API, it’s faster than we can measure: DOM updates take almost no time, especially in comparison to network interaction. Incremental DOM updates and minimizing rendering shift are not hard problems to solve when it doesn’t need to cover all use cases. Interacting with Web APIs via web-sys is a little annoying, but gets a lot better when you write a few basic abstractions.

We actually started the frontend in TypeScript, but switched over to Rust for these main reasons. WebAssembly is already at least as fast as JavaScript and has a long way to go, as it is directly intended for native compilation. Furthermore, direct interfacing with Web APIs is on the horizon for WebAssembly, which we hope to leverage eventually.

Our WebAssembly binary is not the smallest as of right now (260KB in release mode), but we are always open to improve that situation and have already spent some effort on it. Still, it’s much easier to garbage-collect native code than JavaScript, so the code size will likely not increase very much. Already, the Web API bindings generated by wasm-bindgen are limited to every API you actually use, not all that you have enabled.

Dioxus?

From our knowledge, Dioxus requires state tracking on the server side, as well as server-side rendering. Both of these are fundamentally incompatible with end-to-end encryption, which immediately disqualifies it from being used in kittehlist.

htmx?

Htmx means server-side rendering, so it shares all of the problems of Dioxus.

Additionally, we want to write clients that do not speak HTML, including TUI or desktop clients. Therefore, we actually want to have a REST API. (Mobile clients could be solved with Dioxus without a REST API.)

My browser plugin doesn’t work on kittehlist!

This is because of kittehlist’s strict CSP, which effectively disables all JavaScript that kittehlist isn’t serving itself. It is possible to disable the CSP on the server-side, see the configuration reference. However, this opens up your client to various attacks that could compromise your list data, including XSS attacks and malicious plugins. We do not recommend disabling the CSP.

Will there be more databases supported?

Possibly. We’re focusing on PostgreSQL as it’s probably the best currently-available database that’s supported by diesel, our ORM. Diesel also supports MySQL and sqlite, so these are on the table. Databases not supported by diesel will not be considered.

What is the roadmap / release plan? When will it be stable?

No idea. This is a hobby project, and we have other interests too. However, it’s likely that we’ll start deploying kittehlist publicly as soon as it matches kaufkauflist in functionality.