Constraints

• Guidelines must be either followed or a rationale for breaking the guideline must be given in a comment nearby

UI

• UI should be hard to use wrong.
• User experience should only be disturbed when necessary.
• UI must be consistent:
  • Colors
  • Use toolbars
  • Reuse components (in storybook)
  • Keybindings
  • personified error messages
  • etc.

Rationale: to support main goal

Data Consistency

• Users always see the latest data.
• The data from the backend is the single source of truth. I.e., in conflicting scenarios always the backend takes preference.
• In offline scenarios the frontend gets read-only.

Rationale: we prefer collaboration over offline use.

Backend

• We use REST with JSON
• API calls should be for interactive use and as such terminate within parts of a second, five seconds maximum, see Graceful Shutdown for more information.

Cookies and Local Store

Should be used as little as possible

• Cookies should be only used for login-related information:
  • auth: AUTH_SESSION
  • keycloak: KEYCLOAK_IDENTITY
  • nextcloud: nc_token/nc_username
• Session Store should be also only used for login-related information:
  • authority
  • client_id
  • oidc.user:https://auth.permaplant.net/realms/PermaplanT:PermaplanT-* (Prod, ...)
  • backend_version (to be able to detect old versions of backend)
• Local Store should be only used for user-changes that should be remembered:
  • darkMode
  • i18nextLng
  • viewing state

Graceful Shutdown

Actix by default handles shutdowns (see here for reference).
As soon as the signal SIGTERM is issued to the backend no new connections will be accepted.

• Still running connection will be finished or terminated after 5sec.
• API requests should ideally take no longer than a few seconds, with a 5-second limit for logging and optimization purposes.
• Implementing this limit improves convenience for both developers (termination of endless loops) and continuous integration (faster restart on hanging API calls), with minimal complexity in the code.