diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c4984eb..c8ac953 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -12,29 +12,39 @@ This document gives a general rationale behind the chosen architecture and techn Overall, you should be able to work with the source code comfortably from Visual Studio Code, although IntelliJ IDEA may be preferable for the Rust portion. +We use standard `cargo` utilities for Rust testing and linting. For TypeScript static analysis, we use [ESLint](https://eslint.org/). For some further TypeScript unit-testing, we use [vitest](https://vitest.dev/) that is recommended in Tauri docs. For some limited end-to-end testing, we utilize [WebDriver](https://www.w3.org/TR/webdriver/) based approach recommended by Tauri. We go with `selenium-webdriver` framework and `mocha` test runner. More details are in the main README, or see this [Tauri testing tutorial](https://jonaskruckenberg.github.io/tauri-docs-wip/development/testing.html) + ## Project structure - `vite.config.ts` | Configuration for the Vite build system (HTML/JS/CSS processing). Most stuff is generated by Tauri, there's just some extra code related to properly building UIKit and to declaring multiple entry points for different windows. - `tsconfig.json` | Configuration for the TypeScript compiler. Generated by Tauri for now. Later we might want to make it a bit more restrictive. -- `package.json` | List of `npm` dependencies. Mostly just Tauri, UIkit, Less, PostHTML and some packages with types declarations. +- `package.json` and `package-lock.json` | List of `npm` dependencies (and its frozen variant). Mostly just Tauri, UIkit, Less, PostHTML, some packages with types declarations, and testing frameworks. +- `.eslintrc.yml` | Configuration for static code analysis for TS with ESLint. - `src` | The HTML/JS/CSS frontend: - `uikit-theme.less` | A Less file where you can place all custom overrides and hooks for the UIkit widgets. If this grows too much, we should create a `theme` folder with Less files and split the overrides into per-widget files. - `styles.less` | Other relevant styling unrelated to UIkit. Again, if this grows too much, feel free to refactor it into something like `styles` folder. - `main.ts` | The entry point for all JavaScript code. Later we'll probably want different entry points for different windows, but for now it's just a single file. + - `aeon_events.ts` and `aeon_state.ts`| The front-end part of the event-based communication. The first one defines the event processing mechanisms in general, the second defines particular structure with event wrapper API. - `html/window.html` | The default HTML "wrapper" that is extended by individual windows. Later, we'll probably need to add other wrappers for things like dialog windows. - - `html/component` | A preliminary home for the HTML files of self-contained components. + - `html/component-editor` | A directory with HTML files of self-contained components for sketch editor workflow. + - `html/component-analysis` | A directory with HTML files of self-contained components for analysis workflow. + - `html/util` | A directory with various (TypeScript) utilities, data interfaces, and so on. - `html` | Other HTML content goes here. For now, this includes various windows. - `assets` | Any images/icons/whatever. -- `src-tauri` | The rust backend:  + - `tests` | TypeScript unit-tests that will be run with `vitest` framework. For now just very simple example. +- `src-tauri` | The rust backend: - `tauri.conf.json` | Mostly default Tauri config. Might need tweaking once we start working more with windows. - - `cargo.toml`, `build.rs` and `src` | Mostly standard Rust project. + - `icons` | Icon logo files for the app.   + - `resources` | Any kind of files that should be bundled together with the code and easily accessible. For now, we use it to store example models (that must not get lost).   + - `Cargo.toml`, `build.rs` and `src` | Mostly standard Rust project. +- `test` | Folder for end-to-end tests with `selenium` and `mocha` frameworks. For now just very simple example. -## Architecture notes +## Architecture notes (early stage) Since this is very early in the project, these are mostly just ideas regarding how things should work: - - Each window has a data structure which maintains it's whole state in Rust. The reason why this is in Rust is that this data structure might include (a) detached windows or (b) dialogs, in which case it might actually span multiple physical windows. - - We should be able to completely serialise this window state in order to "save" the state of the program. - - The JS/TS front-end sends "input events" which are reflected in the Rust state, which then sends "display events" to the frontend to actually update the contents of inputs. This is similar to what we did in Pythia. It is a bit worse in terms of performance, but should be manageable. - - Each event that changes the internal state should be also saved into an undo/redo stack based on which events can be replayed or reversed. - - The UI consists of self-contained "components". Each component should  only span a specific sub-tree of HTML elements. However, a component can have sub-components. Ideally, sub-components can be detached into separate windows, with a placeholder in the original location.   +- Each window has a data structure which maintains it's whole state in Rust. The reason why this is in Rust is that this data structure might include (a) detached windows or (b) dialogs, in which case it might actually span multiple physical windows. +- We should be able to completely serialise this window state in order to "save" the state of the program. +- The JS/TS front-end sends "input events" which are reflected in the Rust state, which then sends "display events" to the frontend to actually update the contents of inputs. This is similar to what we did in Pythia. It is a bit worse in terms of performance, but should be manageable. +- Each event that changes the internal state should be also saved into an undo/redo stack based on which events can be replayed or reversed. +- The UI consists of self-contained "components". Each component should  only span a specific sub-tree of HTML elements. However, a component can have sub-components. Ideally, sub-components can be detached into separate windows, with a placeholder in the original location.   diff --git a/README.md b/README.md index 8d87bec..08bb706 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,8 @@ Alternatively, if you want to build the tool locally, the instructions are provi The following instructions desribe the local installation of the application and relevant frameworks. We recommend using the pre-built binaries described in the previous section. +For a summary of all technologies and detailed project structure, see `ARCHITECTURE.md`. + ### Installation of dependencies First, make sure you have Rust and NPM installed. For Rust, we recommend following the instructions on [rustlang.org](https://www.rust-lang.org/learn/get-started). For instructions on NPM and Node installation, feel free to check [their website](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).