diff --git a/proposed/0000-awesome-frontend.md b/proposed/0000-awesome-frontend.md index eb37d1b..c7d3e95 100644 --- a/proposed/0000-awesome-frontend.md +++ b/proposed/0000-awesome-frontend.md @@ -8,23 +8,70 @@ Proposed ## Summary [summary]: #summary -The Kvm [frontend](https://github.com/kartevonmorgen/kartevonmorgen) shall be accessible -from multiple clients (browser, mobile) and the code shall be maintainable. +The Karte von morgen [frontend](https://github.com/kartevonmorgen/kartevonmorgen) +shall be accessible from multiple clients (browser, mobile) and the code shall be maintainable. ## Context [context]: #context -> This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. +The current frontend is in a bad state. +The following issues need to be solved to change the situation: + +- **Maintainability** + Due to the untyped programming language JavaScript most types of code refactoring are risky to realize. + This gets emphasized by external dependencies that easily can break the web application. + Often a simple dependency update leads to multiple hours of fighting the dependency hell. + Unfortunately a handful of bugs don't occur during the refactoring process but during the + runtime (because JS can't check correctness at compile time). + +- **Complexity** + The current complexity of the codebase is grown due to a lot of dirty quick fixes. + This not only makes it hard for the community to contribute to the project + but it also makes it costly to introduce new features. + +- **Tests** + There are few tests but most of the code is untested. + This makes it even harder to refactor and maintain the project. + +- **File size** + The packed JavaScript bundle size was 5.3 MB some time ago. + In the meanwhile its shrunken to 1.5 MB but that's still a bunch of bytes that + needs to be downloaded at once. ## Decision [decision]: #decision -> This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..." +We will port the whole frontent to [Rust](https://rust-lang.org). +The result will be a [WASM](https://en.wikipedia.org/wiki/WebAssembly) module. + +We made this decision based on following reasons. +We expect to achieve + +- a much better **maintainability** because: + - Rust is statically typed + - refactoring is easy (the compiler does a very good job) + - the package manager [Cargo](https://doc.rust-lang.org/stable/cargo/) provides + a reliable dependency management + - most mistakes will popup at compile-time +- a reduced **complexity** because we can get rid of most legacy code +- a more efficient **testing** because we can focus on business logic + (instead of testing trivial things like it is required in JavaScript) +- a mobile friendly **file size** because the app is packed in a binary format + (instead of text like it is with JavaScript) +- a better API integration because we can **share** modules with the backend (OpenFairDB) + that is also written in Rust. ## Consequences [consequences]: #consequences -> This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. +The decision has the following consequences: + +- developers need to know or learn Rust +- [Leaflet](https://leafletjs.com/) can't be integrated directly +- the admin frontend of the OpenFairDB can be merged into the frontend +- probably the whole codebase needs to be ported at once +- we can't use component libraries that are based on React +- the app won't work with old browsers ## References [references]: #references