Architectural Decision (New Frontend)

frontend/README.md

@@ -1,22 +1,5 @@
-# Frontend Deployment for Development
+# fAIr Frontend Development
 
-![example workflow](https://github.com/omranlm/TDB/actions/workflows/frontend_build.yml/badge.svg)
-## Getting Started
+# Status
 
-## Install node
-
-This project is tested with Node v14.17.3 and Node v16.14.2
-
-### Install Dependencies
-
-`npm install --legacy-peer-deps`
-
-### Create .env file inside root dir 
-
-Put your credentials inside .env by following .env [sample](https://github.com/omranlm/TDB/blob/main/frontend/.env%20sample) . 
-
-### Start development server
-
- `npm start`
-
-#### Note : Build and Run Backend first by following [this](https://github.com/hotosm/fAIr/blob/master/backend/README.md) before building frontend . 
+Architecture decision in progress. See [Docs](./docs/index.md)

frontend/docs/architecture/adr-choose-drawing-library/adr1.md

@@ -0,0 +1,30 @@
+# Architecture Decision Record 1: X for Drawing Library
+
+Date: 01/09/2024
+
+# Context
+
+We are developing a web application that requires a drawing library for creating, editing, and managing spatial geometries (polygons). The selected library must integrate well with our existing React.js framework and web mapping library, support key drawing features, offer an easy to use API, and be fast and efficient.
+
+## Decision Drivers
+
+- Compatible with web mapping library
+- Lightweight
+- Flexible API
+
+## Considered Options
+
+- [Terra Draw](https://github.com/JamesLMilner/terra-draw): Terra Draw centralizes map drawing logic and provides a host of out-of-the-box drawing modes that work across different JavaScript mapping libraries. It also allows you to bring your own modes!
+- [Mapbox GL Draw](https://github.com/mapbox/mapbox-gl-draw): Strong performance with WebGL rendering, excellent support for vector data, works well with Mapbox and Maplibre GL.
+
+# Decision
+
+Decision will be based on the web mapping library approved.
+
+# Status
+
+Proposed.
+
+# Consequences
+
+

frontend/docs/architecture/adr-choose-styling-library/adr1.md

@@ -0,0 +1,62 @@
+# Architecture Decision Record 1: Tailwind CSS for Styling Library
+
+Date: 01/09/2024
+
+# Context
+
+We are building the fAIr website that requires a responsive and customizable user interface. The stying must be consistent and modern, ensuring a great user experience. The development team has experience using custom CSS but wants to explore CSS frameworks that can save time and effort. We are looking for a framework that is easy to use, customizable, has a large community for support and has a compatible license with HOT.
+
+## Decision Drivers
+
+- Easy to use: We want a framework that is simple to learn and can be integrated into our development workflow.
+
+- Customizable: We want a framework that can be customized to match the HOT brand guidelines and theme.
+
+- Large community support: We want a framework that has an active community of developers, libraries, and designers that can provide help and resources when needed.
+
+- Time-saving: We want a framework that can save time and effort in styling the UI.
+
+- License: We want a framework that is open source and compatible with HOT licensing requirement.
+
+- Size & Performance: We want a framework that ships small CSS to the client, and would not bloat the website.
+
+## Considered Options
+
+- [Bootstrap](https://getbootstrap.com/): A popular CSS framework with a lot of pre-built components and a large community of developers.
+
+- [Material UI](https://mui.com/material-ui/): A CSS framework based on Google's Material Design language with pre-built components for UI development.
+
+- [Chakra UI](https://v2.chakra-ui.com/): Create accessible React apps with speed.
+
+- SCSS: CSS with superpowers.
+
+- [Tailwind CSS](https://tailwindcss.com/): A utility-first CSS framework with a focus on customization and efficiency.
+
+# Decision
+
+After considering the options, we will use Tailwind CSS for the following reasons:
+
+- Easy to use: Tailwind's approach is simple and easy to understand. Its utility classes make building a UI faster.
+
+- Customizable: Tailwind allows for customization by providing a set of configuration files that allow developers to modify the framework's default styles with ease.
+
+- Large community support: Tailwind has a very active community of developers, open source libraries, and designers that are consistently creating new resources, plugins, and tools.
+
+- Time-saving: Tailwind can save time, enabling the team to focus on other areas of the project.
+
+- License: Tailwing's license is MIT, which complies with HOT licensing requirement.
+
+- Size & Performance: Unlike other considered options, Tailwing is smaller and ships less than 10KB to the client.
+
+
+We will use Tailwind CSS's utility classes to build the UI for our project. The development team will use its atomic and modular design system to write efficient and scalable CSS code. We will leverage Tailwind's pre-built templates and visual components to speed up the development process while utilizing custom styles to match the branding and theme of HOT.
+
+# Status
+
+Proposed.
+
+# Consequences
+
+- New developers onboarding this project may face a slight learning curve.
+- Since most UI elements will be built from scratch, there could be minor development slowdown compared to using component-based frameworks like Material UI or Chakra UI. Although component-based frameworks may also introduce some learning curve and inflexibility.
+

frontend/docs/architecture/adr-choose-web-framework/adr1.md

@@ -0,0 +1,35 @@
+# Architecture Decision Record 1: React JS for Web Development Framework
+
+Date: 01/09/2024
+
+# Context
+
+We are building the fAIr platform that requires high performance, fast development cycles, and scalability. The development team is proficient in React and Next.js, and HOT has a history of using React.js for most of its projects. To maintain consistency and leverage existing knowledge, we are considering web development frameworks that align with our team's skill set and project requirements.
+
+## Decision Drivers
+
+- Speed of development: minimizing the time required to build and deploy features.
+- Performance: ensuring the web application is highly performant, especially in terms of loading times and SEO.
+- Familiarity with the framework: developers are experienced with React and Next.js, reducing the need for additional training.
+- Ease of deployment: Avoid vendor lock-in during deployment.
+
+## Considered Options
+
+- [React.js](https://react.dev/): Familiarity with the team, widely used in the company, rich ecosystem of libraries.
+
+- [Next.js](https://nextjs.org/): Built on top of React, offers server-side rendering and static site generation out of the box, optimized for performance and SEO, familiar to the team.
+
+
+# Decision
+
+We will use React.js as the framework for this project. This decision leverages the team's extensive knowledge of React.js and its established use within HOT. Additionally, React.js offers straightforward deployment options, which potentially aligns well with HOT's current DevOps processes. In contrast, while Next.js provides some advanced features, concerns over potential vendor lock-in with Vercel and the complexity of alternative deployment methods make it less suitable for our needs at this time. React.js ensures a smoother and more efficient deployment process without compromising our flexibility.
+
+The two options (React.js and Next.js) are licensed under very permissive open-source licenses (MIT) meaning they align with HOT license requirements.
+
+# Status
+
+Proposed.
+
+# Consequences
+
+New developers may need a brief period to adapt to React.js if they are only familiar with other frameworks.

frontend/docs/architecture/adr-choose-webmap-library/adr1.md

@@ -0,0 +1,39 @@
+# Architecture Decision Record 1: Maplibre GL for Web Mapping Library
+
+Date: 01/09/2024
+
+# Context
+
+We are building a web application that requires rendering medium to large sized polygons on a map interface. The solution must integrate well with React.js, be fast and performant, and should not significantly increase the bundle size. The development team is familiar with OpenLayers, Leaflet, MapLibre GL, and Deck.GL, making them all viable options. Given the nature of our use case, the focus is on performance, rendering capabilities, and overall size efficiency.
+
+## Decision Drivers
+
+- Ability to render medium to large polygons efficiently.
+- Integration with React.js libraries.
+- Performance, particularly in rendering and interaction with polygon geometries.
+- Library size and impact on the overall application bundle.
+- License
+
+## Considered Options
+
+- [OpenLayers](https://openlayers.org/): Powerful for handling complex geometries, good performance for rendering large datasets, robust features for mapping. However, it has a larger bundle size compared to others, and may require more customization to integrate smoothly with React.js.
+
+- [Leaflet](https://leafletjs.com/): Lightweight, simple API, and easy integration with React.js (via react-leaflet). However, performance may degrade with large polygons, not as feature-rich for advanced rendering.
+
+- [MapLibre GL](https://maplibre.org/maplibre-gl-js/docs/): Good performance, especially with vector tiles and polygons, integrates well with React.js, supports WebGL for high-performance rendering. However, it may be slightly larger than Leaflet but smaller than OpenLayers, and lacks some advanced 3D features compared to Deck.GL.
+
+- [Deck.GL](https://deck.gl/): Excellent for rendering large-scale data visualizations, high-performance WebGL-based rendering, good React.js integration. However, it has the largest bundle size, may be overkill for simpler polygon rendering.
+
+# Decision
+
+We will use MapLibre GL as the web mapping library for this project. It strikes the best balance between performance, polygon rendering capabilities, and integration with React.js. MapLibre GL offers good WebGL-based performance, making it suitable for rendering medium to large polygons, and its size is moderate compared to OpenLayers and Deck.GL.
+
+All four options (OpenLayers, Leaflet, MapLibre GL, and Deck.GL) are licensed under very permissive open-source licenses (BSD or MIT) meaning they align with HOT license requirements.
+
+# Status
+
+Proposed.
+
+# Consequences
+
+This decision allows us to efficiently render medium to large polygons while maintaining good performance and keeping the application bundle size manageable. Integration with React.js should be smooth, but there may be some learning curve in managing advanced features or configurations. The team will also need to monitor and manage bundle size as new features are added to avoid bloat.

frontend/docs/architecture/template.md

@@ -0,0 +1,29 @@
+# Architecture Decision Record X: ....
+
+Date: XX/XX/XXXX
+
+# Context
+
+We are building a web application ...
+
+## Decision Drivers
+
+- Driver 1:
+- Driver 2:
+
+## Considered Options
+
+- Option A
+- Option B
+
+# Decision
+
+We will...
+
+# Status
+
+Proposed or Accepted or Deprecated or Superseded
+
+# Consequences
+
+This might affect ...

frontend/docs/index.md

@@ -0,0 +1,28 @@
+## Architectural Decisions
+
+The `architecture` folder comprises of subfolders and markdowns that documents the architectural decisions made when deciding on the tools used in developing this project. The template used is based on the simple and popular template -- [Documenting architecture decisions - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), however slightly modified to include the **Date** of the decision. The folder is updated continually when decision making need arises until the end of the project.
+
+## Folder Arrangement
+
+We follow the recommendations from Michael Nygard (quoted below) in the folder arrangement.
+
+> ADRs will be numbered sequentially and monotonically. Numbers will not be reused.
+
+> If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.)
+
+
+In the `architecture` folder there are subfolders for each decision making. In each subfolders, there are ADRs numbered sequentially. Also the numbers are reflected in the _Title_ when you open the ADR.
+
+
+## Quick Links
+
+1. [Framework Decision](./architecture/adr-choose-web-framework/adr1.md)
+2. [Styling Library Decision](./architecture/adr-choose-styling-library/adr1.md)
+3. [Web mapping Library Decision](./architecture/adr-choose-webmap-library/adr1.md)
+4. [Drawing Library Decision](./architecture/adr-choose-drawing-library/adr1.md)
+
+
+## References
+
+- [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture-decision-record?tab=readme-ov-file)
+- [Documenting architecture decisions - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)