Intial Docs Setup

frontend/.env.sample

@@ -35,6 +35,13 @@ VITE_MIN_TRAINING_AREA_SIZE = 5797
 # Default value: 5242880 bytes (5 MB).
 VITE_MAX_TRAINING_AREA_UPLOAD_FILE_SIZE = 5242880
 
+
+# The name of the application.
+# This is used in the geojson-to-osm utility function to include the app name in the XML root element.
+# Data type: String (e.g., fAIr-AI Assisted Mapping).
+# Default value: "fAIr".
+VITE_APP_NAME =  "fAIr"
+
 # The current version of the application.
 # This is used in the OSM redirect callback when a training area is opened in OSM.
 # Data type: String (e.g., v1.1).

frontend/.gitignore

@@ -24,4 +24,5 @@ dist-ssr
 *.sw?
 
 tsconfig.app.tsbuildinfo
-tsconfig.node.tsbuildinfo
+tsconfig.node.tsbuildinfo
+docs/.vitepress/cache 

frontend/README.md

@@ -2,6 +2,8 @@
 
 This project is a frontend web application built using **React 18**, **TypeScript**, and **Vite**. The app leverages modern libraries such as **@hotosm/ui**, and **Shoelace** for UI components, and **React Router** for client-side routing.
 
+For detailed information on how to use and contribute to this project, please visit our [Documentation](https://f-a-ir-docs.vercel.app/).
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -65,7 +67,6 @@ Here's an overview of the folder structure:
 │ ├── enums/ - Reusable enums.
 | |── features/ - Contains the main features of the application.
 │ ├── hook/ - Reusable hooks.
-│ ├── layouts/ - Core layouts of the application.
 │ ├── services/ - Axios API clients and services.
 │ ├── styles/ - Global styles.
 │ ├── types/ - Reusable types.
@@ -78,7 +79,7 @@ Here's an overview of the folder structure:
 
 ## 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.
+The project utilized the following codebase standards:
 
 #### ESLint
 
@@ -110,6 +111,10 @@ We use the `kebab-case` to name all files. This helps to keep your codebase cons
 
 See [the documentation](./docs/) for more information on the architectural decisions.
 
+#### File Organization
+
+The file organization is inspired by [Bulletproof React](https://github.com/alan2207/bulletproof-react) with a few modifications.
+
 ## Contributing
 
 Please refer to the [CONTRIBUTING](../CONTRIBUTING.md) guide for more information.
@@ -138,8 +143,9 @@ fAIr also bundles portions of the following open source software.
 - [React Router (MIT)](https://github.com/remix-run/react-router).
 - [Terra Draw (MIT)](https://github.com/JamesLMilner/terra-draw).
 - [Vaul (MIT)](https://github.com/emilkowalski/vaul).
+- [Vitest (MIT)](https://github.com/vitest-dev/vitest).
 - [XMLBuilder2 (MIT)](https://github.com/oozcitak/xmlbuilder2).
 - [React Helmet Async (Apache-2.0)](https://github.com/staylor/react-helmet-async).
 - [Maplibre GL JS (BSD-3-Clause)](https://github.com/maplibre/maplibre-gl-js).
 - [PMTiles (BSD-3-Clause)](https://github.com/protomaps/PMTiles).
-- [React Medium Image Zoom (BSD-3-Clause)](https://github.com/rpearce/react-medium-image-zoom).
+- [React Medium Image Zoom (BSD-3-Clause)](https://github.com/rpearce/react-medium-image-zoom).

frontend/docs/.vitepress/config.ts

@@ -0,0 +1,71 @@
+import { defineConfig } from 'vitepress';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "fAIr",
+  description: "AI-powered assistant that amplify your mapping efforts intelligently and quickly, helping you map smarter and faster.",
+  ignoreDeadLinks: true,
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Get Started', link: '/getting-started' }
+    ],
+
+    sidebar: [
+      {
+        text: 'fAIr Documentation',
+        items: [
+          {
+            text: 'Introduction', items: [
+              { text: 'Getting Started', link: '/getting-started' },
+              { text: 'Dependencies', link: '/dependencies' },
+            ]
+          },
+          {
+            text: 'Architecture Decision Records',
+            link: '/architecture/README.md',
+            items: [
+              {
+                text: 'Web Framework', items: [
+                  { text: 'ADR1', link: '/architecture/adr-choose-web-framework/adr1.md' },
+                  { text: 'ADR2', link: '/architecture/adr-choose-web-framework/adr2.md' },
+
+                ]
+              },
+              {
+                text: 'Styling Library', items: [
+                  { text: 'ADR1', link: '/architecture/adr-choose-styling-library/adr1.md' },
+                  { text: 'ADR2', link: '/architecture/adr-choose-styling-library/adr2.md' },
+                  { text: 'ADR3', link: '/architecture/adr-choose-styling-library/adr3.md' },
+                ]
+              },
+              {
+                text: 'Webmap Library', items: [
+                  { text: 'ADR1', link: '/architecture/adr-choose-webmap-library/adr1.md' },
+                  { text: 'ADR2', link: '/architecture/adr-choose-webmap-library/adr2.md' },
+                ]
+              },
+              {
+                text: 'Drawing Library', items: [
+                  { text: 'ADR1', link: '/architecture/adr-choose-drawing-library/adr1.md' },
+                  { text: 'ADR2', link: '/architecture/adr-choose-drawing-library/adr2.md' },
+                ]
+              },
+              { text: 'Package Manager', link: '/architecture/adr-choose-package-manager/adr1.md' },
+              { text: 'Programming Language', link: '/architecture/adr-choose-language/adr1.md' },
+              { text: 'Bundler', link: '/architecture/adr-choose-bundler/adr1.md' },
+              { text: 'Testing Library', link: '/architecture/adr-choose-testing-library/adr1.md' }
+            ]
+          },
+
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/hotosm/fair' }
+    ]
+  }
+})

frontend/docs/README.md → frontend/docs/architecture/README.md

@@ -1,4 +1,4 @@
-## Architectural Decisions
+# 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.
 
@@ -14,13 +14,14 @@ In the `architecture` folder there are subfolders for each decision making. In e
 
 ## 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)
-5. [Package Manager Decision](./architecture/adr-choose-package-manager/adr1.md)
-6. [Programming Language Decision](./architecture/adr-choose-language/adr1.md)
-7. [Bundler Decision](./architecture/adr-choose-bundler/adr1.md)
+1. [Framework Decision](./adr-choose-web-framework/adr1.md)
+2. [Styling Library Decision](./adr-choose-styling-library/adr1.md)
+3. [Web mapping Library Decision](./adr-choose-webmap-library/adr1.md)
+4. [Drawing Library Decision](./adr-choose-drawing-library/adr1.md)
+5. [Package Manager Decision](./adr-choose-package-manager/adr1.md)
+6. [Programming Language Decision](./adr-choose-language/adr1.md)
+7. [Bundler Decision](./adr-choose-bundler/adr1.md)
+8. [Testing Library Decision](./adr-choose-testing-library/adr1.md)
 
 ## References
 

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

@@ -0,0 +1,39 @@
+# Architecture Decision Record 1: Use Vitest as the Testing Library
+
+Date: 31/12/2024
+
+# Context
+
+We are building a web application that requires a robust and maintainable testing strategy to ensure code quality, reliability, and confidence in our continuous integration pipeline. We want a solution that is easy to set up, widely supported in the JavaScript community, and provides both unit and integration testing capabilities.
+
+## Decision Drivers
+
+- Developer Experience: We want a testing framework with a fast feedback loop, minimal configuration, and good integration with Vite.
+
+- Performance and Modern Features: We need a tool that executes tests quickly and supports cutting-edge features such as native ESM, TS integration, and fast in-memory testing.
+
+## Considered Options
+
+- Use Jest
+    - Pros: Widely adopted, minimal configuration, built-in mocking and assertion, and good performance.
+    - Cons: Primarily oriented around JavaScript/TypeScript; might not seamlessly integrate with other environments. Experimental support for ECMAScript modules. Does not integrate natively with Vite.
+
+- Use Mocha + Chai
+    - Pros: Highly customizable, flexible setup with well-known assertion library (Chai).
+    - Cons: Requires additional libraries for mocking, slightly more complex configuration.
+
+- Use Vitest
+    - Pros: Built on top of Vite, offering lightning-fast test runs and modern ESM support; straightforward setup; good integration with React and TypeScript.
+    - Cons: Newer project with a smaller community compared to Jest; may have more limited ecosystem for plugins.
+
+# Decision
+
+We will use Vitest as our testing tool. It integrates easily with modern front-end tooling, requires minimal configuration, has native ESM support and TypeScript integration making it suitable for our current and future needs.
+
+# Status
+
+Accepted.
+
+# Consequences
+
+By choosing Vitest, we gain a testing framework that is quick to run and easy to configure, encouraging a fast feedback loop during development. Vitest’s seamless integration with modern build tools and frameworks allows us to maintain a simpler development environment. However, because Vitest is newer and has a smaller ecosystem than Jest, we may need to be mindful of plugin availability and community support for very specialized testing needs.

frontend/docs/dependencies.md

@@ -0,0 +1,27 @@
+# Dependencies
+
+This document lists the major dependencies used in this application along with their licenses, brief descriptions, and links to their respective pages or repositories.
+
+| Dependency    | License       | Description                                      | Link                                      |
+|---------------|---------------|--------------------------------------------------|-------------------------------------------|
+| React         | MIT           | A JavaScript library for building user interfaces| [React](https://reactjs.org/)             |
+| @shoelace-style/shoelace | MIT           | A collection of professionally designed, every day UI components built on a framework-agnostic technology | [Shoelace](https://shoelace.style/) |
+| @tanstack/react-query    | MIT           | Hooks for fetching, caching and updating asynchronous data in React | [React Query](https://tanstack.com/query/latest) |
+| @tanstack/react-table    | MIT           | Headless UI for building powerful tables & datagrids | [React Table](https://tanstack.com/table/latest) |
+| @terraformer/wkt         | MIT           | Well-Known Text (WKT) parser and serializer for Terraformer | [Terraformer WKT](https://github.com/terraformer-js/terraformer) |
+| @turf/js               | MIT           | A modular geospatial engine written in JavaScript and TypeScript | [Turf JS](https://github.com/Turfjs/turf) |
+| clsx                     | MIT           | A tiny utility for constructing `className` strings conditionally | [Clsx](https://github.com/lukeed/clsx) |
+| framer-motion            | MIT           | A production-ready motion library for React | [Framer Motion](https://www.framer.com/motion/) |
+| react-confetti-explosion | MIT           | Confetti explosion animation for React | [React Confetti Explosion](https://github.com/herrethan/react-confetti-explosion) |
+| react-dropzone           | MIT           | Simple React hook to create a HTML5-compliant drag'n'drop zone for files | [React Dropzone](https://github.com/react-dropzone/react-dropzone) |
+| react-error-boundary     | MIT           | Simple reusable React error boundary component | [React Error Boundary](https://github.com/bvaughn/react-error-boundary) |
+| react-markdown           | MIT           | Render Markdown as React components | [React Markdown](https://github.com/remarkjs/react-markdown) |
+| remark-gfm               | MIT           | Plugin to support GitHub Flavored Markdown (GFM) | [Remark GFM](https://github.com/remarkjs/remark-gfm) |
+| tailwind-merge           | MIT           | Utility to merge Tailwind CSS classes | [Tailwind Merge](https://github.com/dcastil/tailwind-merge) |
+| terra-draw               | MIT           | A drawing library for interactive maps | [Terra Draw](https://github.com/JamesLMilner/terra-draw) |
+| vaul                     | MIT           | A drawer component for React | [Vaul](https://github.com/emilkowalski/vaul) |
+| xmlbuilder2              | MIT           | A modern, fast, and powerful XML builder for Node.js | [Xmlbuilder2](https://github.com/oozcitak/xmlbuilder2) |
+| maplibre-gl              | BSD-3-Clause  | A mapping library for rendering maps with WebGL | [MapLibre GL](https://github.com/maplibre/maplibre-gl-js) |
+| pmtiles                  | BSD-3-Clause           | A compact, efficient format for storing and serving vector tiles | [PMTiles](https://github.com/protomaps/PMTiles) |
+| react-medium-image-zoom  | BSD-3-Clause           | Medium.com style image zoom for React | [React Medium Image Zoom](https://github.com/rpearce/react-medium-image-zoom) |
+| react-helmet-async       | Apache-2.0           | Thread-safe Helmet for React 16+ and friends | [React Helmet Async](https://github.com/staylor/react-helmet-async) |

frontend/docs/getting-started.md

@@ -0,0 +1,118 @@
+# Getting Started
+
+## Installation
+
+Note: This project is tested with Node v20.13.1.
+
+1. Clone the repository:
+
+```bash
+git https://github.com/hotosm/fAIr.git
+cd fAIr/frontend
+```
+
+2. Install dependencies using [pnpm](https://pnpm.io/), [npm](https://www.npmjs.com/), or [yarn](https://yarnpkg.com/). This project uses pnpm:
+
+```bash
+pnpm install
+```
+
+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.
+│ ├── config/ - Environment variables configuration.
+│ ├── constants/ - App UI contents and constants.
+│ ├── enums/ - Reusable enums.
+| |── features/ - Contains the main features of the application.
+│ ├── hook/ - Reusable hooks.
+│ ├── services/ - Axios API clients and services.
+│ ├── styles/ - Global styles.
+│ ├── types/ - Reusable types.
+│ ├── utils/ - Utility functions, application content and constants.
+│ └── 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 utilized the following codebase standards:
+
+#### 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. To format run the code below in the terminal.
+
+```bash
+1. pnpm/npm/yarn format
+
+2. pnpm/npm/yarn format:check
+```
+#### Tests
+
+[Vitest](https://vitest.dev/) is a used to write the tests in the codebase. To run the tests, run the command below:
+
+```bash
+pnpm/npm/yarn test
+```
+
+#### Documentation
+
+[Vitepress](https://vitepress.dev/) is a used to power this documentation site. To update the docs check the `docs` folder and run the command below to preview your changes:
+
+```bash
+pnpm/npm/yarn docs:dev
+```
+
+#### 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.
+
+#### Architectural Decisions
+
+See [the documentation](./architecture/README.md) for more information on the architectural decisions.
+
+#### File Organization
+
+The file organization is inspired by [Bulletproof React](https://github.com/alan2207/bulletproof-react) with a few modifications.

frontend/docs/index.md

@@ -0,0 +1,26 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Welcome to fAIr's Developer Doc."
+  text: ""
+  tagline: fAIr is an AI-powered assistant that amplify your mapping efforts intelligently and quickly, helping you map smarter and faster.
+  actions:
+    - theme: brand
+      text: Visit fAIr
+      link: https://fair-dev.hotosm.org
+    - theme: alt
+      text: Get Started
+      link: /getting-started
+features:
+- title: Developer Friendly
+  details: Clean and easy-to-understand codebase.
+- title: Best Practices
+  details: Built with modern technologies and tools.
+- title: Dependencies
+  details: Minimal dependencies for high performance.
+- title: Architectural Decisions
+  details: Thoughtfully designed for efficiency.
+---
+