Merge pull request #288 from hotosm/revamp/frontend

New Frontend : Progress

.gitignore

@@ -19,6 +19,7 @@ postgres-data/*
 frontend/build
 
 # misc
+.DS_Store
 frontend/.DS_Store
 frontend/.env.local
 frontend/.env.development.local

frontend/.env.sample

@@ -0,0 +1,3 @@
+VITE_BASE_API_URL = 'http://localhost:8000/api/v1/' # backend api url
+VITE_MATOMO_ID= 0 
+VITE_MATOMO_APP_DOMAIN = "subdomain.hotosm.org"

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/.prettierignore

@@ -0,0 +1,3 @@
+# Ignore artifacts:
+build
+coverage

frontend/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "dsznajder.es7-react-js-snippets",
+    "mariusalchimavicius.json-to-ts",
+    "bradlc.vscode-tailwindcss"
+  ]
+}

frontend/README.md

@@ -1,22 +1,114 @@
-# Frontend Deployment for Development
+# fAIr Frontend
 
-![example workflow](https://github.com/omranlm/TDB/actions/workflows/frontend_build.yml/badge.svg)
-## Getting Started
+This project is a frontend web application built using **React 18**, **TypeScript**, and **Vite**. The app leverages modern libraries such as **@hotosm/ui**, **Shoelace**, and **Framer Motion** for UI components, and **React Router** for client-side routing.
 
-## Install node
+## Table of Contents
 
-This project is tested with Node v14.17.3 and Node v16.14.2
+- [Installation](#installation)
+- [Build](#build)
+- [Folder Structure](#folder-structure)
+- [Codebase Standards](#codebase-standards)
+- [Contributing](#contributing)
+- [License](#license)
 
-### Install Dependencies
+## Installation
 
-`npm install --legacy-peer-deps`
+Note: This project is tested with Node v20.13.1.
 
-### Create .env file inside root dir 
+1. Clone the repository:
 
-Put your credentials inside .env by following .env [sample](https://github.com/omranlm/TDB/blob/main/frontend/.env%20sample) . 
+```bash
+git https://github.com/hotosm/fAIr.git
+cd fAIr/frontend
+```
 
-### Start development server
+2. Install dependencies using [pnpm](https://pnpm.io/), [npm](https://www.npmjs.com/), or [yarn](https://yarnpkg.com/). This project uses pnpm:
 
- `npm start`
+```bash
+pnpm install
+```
 
-#### Note : Build and Run Backend first by following [this](https://github.com/hotosm/fAIr/blob/master/backend/README.md) before building frontend . 
+3. Create .env file inside root dir by following .env [sample](./.env.sample).
+
+```bash
+touch .env
+```
+
+4. Start the development server:
+
+```bash
+pnpm dev
+```
+
+The app will be available at **http://127.0.0.1:5173**. To change the default port, you can edit the [vite config](./vite.config.mts).
+
+## Build
+
+```bash
+pnpm build
+```
+
+This will create an optimized build of your app in the dist/ folder, which can be deployed.
+
+## Folder Structure
+
+Here's an overview of the folder structure:
+
+```markdown
+├── public/ # Static assets like favicon, robots.txt and manifests.
+├── src/ # main application codes are here.
+│ ├── app/ # Contains the application routes and providers.
+│ ├── assets/ # Static assets specific to the app (images, icons, etc.).
+│ ├── components/ # Reusable components and layouts.
+│ ├── hook/ # Reusable hooks.
+│ ├── styles/ # Global styles.
+│ ├── utils/ # Utility functions, application content and constants.
+│ ├── config/ # Environment variable configuration object.
+│ ├── services/ # Axios API clients and services.
+│ ├── types/ # Reusable types.
+│ └── main.tsx # Entry point of the React app.
+├── docs/ # ARD documentation for some of the decisions made for the app.
+└── vercel.json # To prevent the custom 404 page from Vercel when a route is visited. (This is just for the demo site deployed on Vercel.)
+└── ... # Other configuration files like tsconfig.json, vite.config.mts etc.
+```
+
+## Codebase Standards
+
+The project standards are crucial for maintaining code quality, consistency, and scalability in a React application. By establishing and adhering to a set of best practices, developers can ensure that the codebase remains clean, organized, and easy to maintain.
+
+#### ESLint
+
+ESLint is used to maintain code quality and adhering to coding standards.
+
+#### Prettier
+
+Prettier is a used to maintain consistent code formatting in the project.
+
+#### TypeScript
+
+This codebase is written in TypeScript.
+
+#### Absolute imports
+
+We use absolute imports (such as `@/components`, `@/hooks`, etc.), to make it easier to move files around and avoid messy import paths such as `../../../component`.
+
+#### File naming conventions
+
+We use the `kebab-case` to name all files. This helps to keep your codebase consistent and easier to navigate.
+
+#### Husky
+
+We use the `husky` to trigger `eslint` and `prettier` configurations when committing code to the repository.
+
+
+## Contributing
+
+Please refer to the [CONTRIBUTING](../CONTRIBUTING.md) guide for more information.
+
+## License
+
+See [LICENSE](../LICENSE).
+
+## Notes
+
+The **@hotosm/ui** installation directory behavior is not consisitent and failed while deploying. However using the CDN and injecting it in the `index.html` works for now.

frontend/docs/README.md

@@ -0,0 +1,25 @@
+## 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)

frontend/docs/architecture/adr-choose-bundler/adr1.md

@@ -0,0 +1,30 @@
+# Architecture Decision Record 1: Use Vite for Development Bundling and Build Tooling
+
+Date: 10/10/2024
+
+# Context
+
+We need a fast and efficient bundler for our React app development. The chosen tool must support modern TypeScript features while offering an optimal development experience.
+
+## Decision Drivers
+
+- Fast hot module replacement (HMR) for efficient development.
+- Support for TypeScript and modern ES modules.
+- Simple configuration.
+
+## Considered Options
+
+- Use [Webpack](https://webpack.js.org/) for bundling, which is highly configurable but can be slow.
+- Use [Vite](https://vitejs.dev/), which offers faster builds and simpler configuration for modern projects.
+
+# Decision
+
+We will use Vite as our bundler and development server due to its superior performance during development and simple configuration.
+
+# Status
+
+Accepted.
+
+# Consequences
+
+There may be some minor limitations in terms of plugins compared to Webpack, but Vite’s ecosystem is growing rapidly, and we don't foresee any complex plugin requirements.

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

@@ -0,0 +1,28 @@
+# 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-drawing-library/adr2.md

@@ -0,0 +1,30 @@
+# Architecture Decision Record 2: Use TerraDraw for Drawing Library
+
+Date: 08/09/2024
+
+# Context
+
+We are developing a web application that requires a drawing library for creating, editing, and managing spatial geometries (mainly 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 Maplibre GL JS.
+- Performant.
+- 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
+
+We’ve chosen TerraDraw as the drawing library for this project. After developing a [demo](https://github.com/jeafreezy/webmap-compare) app to test its functionality, we found that it meets the project's requirements effectively.
+
+# Status
+
+Accepted.
+
+# Consequences
+
+Nil.

frontend/docs/architecture/adr-choose-language/adr1.md

@@ -0,0 +1,30 @@
+# Architecture Decision Record 1: Use Typescript for Development
+
+Date: 10/09/2024
+
+# Context
+
+We are building a web application that requires strong type-checking to reduce runtime errors and improve the overall developer experience. The project will be developed in React, where maintainability and scalability are key concerns.
+
+## Decision Drivers
+
+- Need for type safety to catch errors during development.
+- Improved developer tooling with autocompletion and refactoring support.
+- Compatibility with existing React ecosystem and team expertise in TypeScript.
+
+## Considered Options
+
+- Use [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) with prop-types for basic type checking.
+- Use [TypeScript](https://www.typescriptlang.org/) for stronger, compile-time type checking.
+
+# Decision
+
+We will use TypeScript for this React project to ensure better maintainability, reduce bugs, and take advantage of static type-checking.
+
+# Status
+
+Accepted.
+
+# Consequences
+
+This decision increases the learning curve for developers not familiar with TypeScript but will result in better code quality and fewer runtime errors.

frontend/docs/architecture/adr-choose-package-manager/adr1.md

@@ -0,0 +1,31 @@
+# Architecture Decision Record 1: Use pnpm as the Package Manager
+
+Date: 10/10/2024
+
+# Context
+
+We need a package manager to efficiently manage dependencies for our React application. The solution should support fast installs, and efficient disk space usage.
+
+## Decision Drivers
+
+- Faster and more efficient dependency management.
+- Support for monorepo structure if needed in the future.
+- Reduced disk space usage by avoiding duplicate packages.
+
+## Considered Options
+
+- Use [npm](https://www.npmjs.com/) as the default package manager.
+- Use [Yarn](https://yarnpkg.com/) for faster installs and better cache management.
+- Use [pnpm](https://pnpm.io/), which offers fast installs and reduced disk space usage.
+
+# Decision
+
+We will use pnpm for managing dependencies due to its speed, efficiency, and ability to save disk space by avoiding redundant packages.
+
+# Status
+
+Accepted.
+
+# Consequences
+
+May require some developers to adapt to a different package management workflow if they are unfamiliar with pnpm.