General information

This is a digital tally sheet for use in trusted environments.

You can test it out on https://demo.strichliste.rs

Build

Build with nix

nix build

Build with cargo-leptos

SQLX_OFFLINE=true cargo leptos build --release

Development

With nix

If you have nix direnv

direnv allow .

Otherwise just do

nix develop

then do

mkdir tmp
sqlx database setup
cargo leptos watch -- -d ./tmp/db.sqlite -c ./config_example.yaml

Without Nix / Other instructions

Install the following dependencies:

• rust
• cargo-leptos
• sqlx (sqlx-cli)
• tailwind
• sqlite

# could also be present in a .env
export DATABASE_URL="sqlite:tmp/db.sqlite" # not needed with nix (env is in flake.nix)

mkdir tmp
sqlx database setup
cargo leptos watch -- -d ./tmp/db.sqlite -c ./config_example.yaml

Preparing for build

We use sqlx and compile-time checked queries. This has the drawback of needing a live db to check the queries, which is not possible in build environments. So we "cache" the sqlx queries using the following command:

# this is an alias to scripts/prepare-sqlx
prepare-sqlx

This step is needed in order for the build instructions to work. This step should be done after changing queries and before merging into main.

Project structure

Rules for extending the folder structure

• In each folder that contains other folders it is allowed to add a shared folder (if its not a folder named shared itself)
• Folders should not contain a folder with the same name or a file with the same name. (clippy will enforce this by default for rust files / folders)
• always use singular for folder names

Folder structure

• src

  everything rust related should live inside here

  • backend

    server functions

    • database

      things only related to database interactions

      • model

        structs, new, trait implementation for general purpose traits (Display, Debug)

      • behaviour

        a interaction with the database that can be performed i.e.: create_user.rs send_money.rs

      • misc

        things that don´t fit into either models or behaviours

      • convert

        conversion between foreign or database only types

    • convert

      conversion between database types and backend types
      prefer implementing the From
      file name: {StructNameA}_from_{StructNameB}.rs

    • core

      code that does not interact with the database directly

      • model

        structs, new, trait implementation for general purpose traits ( Display, Debug)

      • behaviour

        a interaction with a backend
        may include multiple interactions with the database

      • misc

        things that don´t fit into either models or behaviours

    • shared

      helper functions that are shared in the entire backend)

  • convert

    conversion between frontend types and backend types
    prefer implementing the From
    file name: {StructNameA}_from_{StructNameB}.rs

  • model

    Models shared by backend and frontend It is allowed to implement functions on these in both frontend and backend Can be DTOs

  • frontend

    code run on the client / at hydration

    • cachinglayer

      client side caching of data while re-fetching from the server

    • style

      tailwind css configs

    • behaviour

      implementations of structs that aren't components

    • component

      reusable components (most things go here)

      • icon

        all used icons should be extracted into a own component

      • user

        everything related to displaying users

      • transaction

        everything related to displaying transactions

      • article

        everything related to displaying articles

    • route

      page views composed of components the files in this directory should be tiny if they get to complex create a component instead

      • articles

        everything related to article only interaction lives under /articles

      • user

        everything related to users only interaction lives under /user

    • shared

      helper functions that are shared in the entire frontend

    • model

      structs, new, trait implementation for general purpose traits (Display, Debug)

  • shared

    helper functions that are needed in the backend and in the frontend

• nix

  all realted to nix except flake.nix and flake.lock

• diagramm

  some uml diagrams made to sketch the db layout

• end2end

  end 2 end test infrastructure

  • tests

    actual end 2 end tests

• migrations

  db migrations generated by sqlx

• public

  all files publicly served by the webserver

  • sounds

    sound files for development

• scripts

  small helper scripts for development and checks