state management and architecture decision

doc/decisions/frontend_architecture_pattern.md

@@ -0,0 +1,44 @@
+# Frontend Architecture Pattern
+
+## Problem
+
+Permaplant needs to be designed with a documented, consistent and maintainable architecture pattern.
+
+## Constraints
+
+The architecture pattern should be
+
+- easy to understand and follow
+- be easy to test
+- be easy to scale
+- be suitable for a large, complex application
+- promote code reuse
+- be well-documented and widely used in the React community
+
+## Considered Alternatives
+
+- [Flux](https://reactjs.org/blog/2014/05/06/flux.html)
+
+  The pattern is rather complicated to understand and leads to a lot of boilerplate.
+
+- [MVVM](https://www.detroitlabs.com/blog/intro-to-mvvm-in-react-with-mobx/)
+
+## Decision
+
+[Bulletproof React](https://github.com/alan2207/bulletproof-react) will be used as frontend architecture and guideline for PermaplanT.
+Choices or derivations of this guidelines will be documented in `doc/architecture`.
+
+## Rationale
+
+Bulletproof React is a set of best practices and conventions that promote code reuse and make it easy to reason about the structure of the application.
+It's simple, easy to understand, and easy to test.
+This makes it a good choice for a large, complex application like Permaplant.
+Additionally, it is well-documented and widely used in the React community, which means that there is a lot of resources and support available for it.
+
+## Implications
+
+## Related Decisions
+
+## Notes
+
+ - "bulletproof react" architecture pattern is developed by the team at Level Up Tutorials. It is not an official pattern by React.

doc/decisions/frontend_state_management.md

@@ -0,0 +1,77 @@
+# Frontend State Management Library
+
+## Problem
+
+PermaplanT is a web application built with React that requires efficient and flexible state management.
+Inside a React application we can usually distinguish between three types of state.
+
+- Local Component State: Is the dropdown open or not, is the link active or not, and so on.
+
+- Global Application State (Synchronous): Local user preferences, Sidenav is open, UI state in a visual design app.
+
+- Server State (Asynchronous): A network request is needed before any state can be derived.
+
+## Constraints
+
+- The state management library must support React and work seamlessly with the rest of the application's technology stack.
+- The library should be well-maintained, have a large community of developers, and a good documentation.
+
+## Considered Alternatives
+
+### Global Application State
+
+- [Redux](https://redux.js.org/)
+  Requires more complex setup, boilerplate and has a steeper learning curve than Zustand.
+- [React context](https://reactjs.org/docs/context.html)
+  Requires complex custom state management solution for complex application
+- [MobX](https://mobx.js.org/)
+  Requires basic understanding of reactive programming - may otherwise lead to inconsistencies and performance problems.
+- [Recoil](https://recoiljs.org/)
+  Recoil is still in experimental state, not yet recommended for production (16.03.2023).
+
+### Server State
+
+- [SWR](https://github.com/vercel/swr)
+  Fewer features than React Query 
+
+## Decision
+
+### Local Component State
+
+  No library is needed. 
+
+#### Rationale
+
+  Managing component state can be accomplished with React features (useState, Context + useReducer).
+
+### Global Application State
+
+  [Zustand](https://github.com/pmndrs/zustand) will be used as the global state management library for PermaplanT.
+
+#### Rationale
+
+Zustand is a lightweight and easy-to-use library that uses hooks, which makes it easy to integrate with React. 
+Its simplicity also reduces the amount of boilerplate code and the need for complex setup and configuration.
+
+### Server State
+
+  [React Query](https://react-query-v3.tanstack.com/) will be used for managing asynchronous state
+
+#### Rationale
+
+  React Query is a feature rich, up to date library for managing asynchronous data. 
+
+## Implications
+
+## Related Decisions
+
+ - Choosing React as the [frontend library](./frontend_ui_framework.md) for PermaplanT
+
+## Notes
+
+## Links
+
+- https://medium.com/readytowork-org/its-zustand-vs-redux-8e24424df713
+- https://tanstack.com/query/latest/docs/react/guides/does-this-replace-client-state
+- https://tanstack.com/query/v4/docs/react/comparison
+