Restructure FDM documentation and add authentication pages

.changeset/slick-bees-post.md

@@ -0,0 +1,5 @@
+---
+"@svenvw/fdm-docs": minor
+---
+
+Extend the pages about core-concepts of FDM, update schema description and reorganize the docs

.vscode/settings.json

@@ -12,5 +12,8 @@
     "editor.formatOnSave": true,
     "[json]": {
         "editor.defaultFormatter": "biomejs.biome"
+    },
+    "[markdown]": {
+        "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
     }
 }

fdm-docs/README.md

@@ -25,13 +25,13 @@ turbo run build
 ```
 
 ## Contributing
+
 We welcome contributions to improve the FDM documentation! See the contributing guidelines in the main FDM repository for details on how to contribute code, documentation, report bugs, and suggest improvements.
 
 ## Made Possible By
 
 FDM is developed by the [Nutriënten Management Instituut](https://www.nmi-agro.nl/) as part of the Horizon Europe projects: [NutriBudget](https://www.nutribudget.eu/) and [PPS BAAT](https://www.handboekbodemenbemesting.nl/nl/handboekbodemenbemesting/pps-baat.htm).
 
-
 ## Contact
 
 Maintainer: @SvenVw

fdm-docs/docs/README.md

@@ -1,21 +1,26 @@
 ---
-sidebar_position: 1
-title: Introduction to FDM
+title: Introduction
+sidebar_position: 0
 ---
 
-The Farm Data Model (FDM) provides a robust and flexible framework for organizing and analyzing agricultural data. Designed with both developers and agronomists in mind, FDM-core offers a standardized schema for representing diverse farm information, enabling seamless data integration, analysis, and decision-making.
+This documentation provides a comprehensive overview of the Farm Data Model (FDM). It is designed to help you understand the core concepts of the FDM, learn how to use it in your own applications, and contribute to its development.
 
-FDM adopts an "Asset-Action" model as its core architectural principle. This model centers around two key concepts: Assets represent physical or conceptual entities within a farm, such as fields, crops, or equipment. Actions, on the other hand, represent operations or events related to these assets, such as planting, fertilizing, or harvesting. This clear separation allows for a granular understanding of farm activities and their impact on different assets.
+## Getting Started
 
-The FDM schema further structures data using a hierarchical approach. This allows for logical grouping and efficient querying. For example, a "field" asset might contain information about its boundaries and connects to various actions where it associated with. These associated actions, like "fertilizer application," include details like date, type of fertilizer, and application rate.
+If you are new to the FDM, we recommend that you start by reading the **[Getting Started](./getting-started/01-what-is-fdm.md)** section. This section provides a high-level overview of the FDM and walks you through the basics of using it in your own applications.
 
-This structured schema ensures data consistency and facilitates interoperability between different farm management systems. By adhering to the FDM schema, developers can build applications that seamlessly integrate with existing farm data, while agronomists can gain valuable insights from standardized data across multiple farms. FDM-core is designed for extensibility, allowing users to add custom attributes and actions to cater to specific needs while maintaining overall schema consistency. This balance of standardization and flexibility ensures FDM can adapt to the evolving needs of modern agriculture.
+## Core Concepts
 
-Key benefits of using the FDM include:
+The **[Core Concepts](./core-concepts/01-database-schema.md)** section provides a detailed explanation of the fundamental components of the FDM. This is the place to go if you want to understand the "what" and the "why" of each concept.
 
-* Improved Data Management: Standardizing data collection and storage through a well-defined schema simplifies data management and analysis.
-* Enhanced Interoperability: Facilitates data exchange between different systems and platforms, enabling a holistic view of farm operations.
-* Data-Driven Decision-Making: Provides a structured framework for analyzing farm data, enabling informed decisions related to resource allocation, crop management, and overall farm productivity.
-* Scalability and Extensibility: The FDM is designed to handle large datasets and can be extended to accommodate new data types and farm practices.
+## Agronomic Calculations
 
-This documentation site provides guides on core concepts, getting started with the FDM libraries, and contributing to the project. For detailed information on the functions and types exported by each package (`fdm-core`, `fdm-data`, `fdm-calculator`), please refer to the **API Reference** section. The **Architecture Overview** page in the Core Concepts section explains the different packages within the FDM monorepo and how they interact.
+The **[Agronomic Calculations](./insights/01-nitrogen-balance.md)** section is dedicated to explaining the calculation engine within the FDM. Here you will find information on how to perform common agronomic calculations, such as nitrogen balance and fertilizer recommendations.
+
+## Contributing to FDM
+
+If you are a developer who wants to contribute to the FDM project, the **[Contributing to FDM](./contributing/01-project-architecture.md)** section is for you. Here you will find information on the project's architecture, how to set up a local development environment, and the release process.
+
+## FDM App
+
+The **[FDM App](./fdm-app/01-introduction-to-fdm-app.md)** section provides a brief introduction to the `fdm-app`, which is a practical, working example of an application that is built with the FDM.

fdm-docs/docs/contributing/01-project-architecture.md

@@ -0,0 +1,24 @@
+---
+title: Project Architecture
+sidebar_label: Project Architecture
+---
+
+The Farm Data Model (FDM) is a monorepo that is managed with `pnpm` workspaces and `turbo`. This structure allows us to manage multiple packages within a single repository, which simplifies dependency management and improves code sharing.
+
+## Monorepo Structure
+
+The FDM monorepo is organized into the following packages:
+
+* **`fdm-core`**: This package contains the core data model, including the database schema, TypeScript types, and JSON schemas.
+* **`fdm-data`**: This package contains the standardized catalogues for crops, fertilizers, and other agricultural inputs.
+* **`fdm-calculator`**: This package contains the agronomic calculation engine, which is used to perform calculations such as nitrogen balance and fertilizer recommendations.
+* **`fdm-app`**: This package is a reference implementation of a farm management application that is built on top of the FDM.
+* **`fdm-docs`**: This package contains the documentation for the FDM project, which is built with Docusaurus.
+
+## `pnpm` Workspaces
+
+`pnpm` workspaces are used to manage the dependencies between the different packages in the monorepo. This allows us to install all the dependencies for all the packages with a single command, and it also ensures that the same version of a dependency is used across all packages.
+
+## `turbo`
+
+`turbo` is a high-performance build system for JavaScript and TypeScript codebases. It is used to orchestrate the build process for the FDM monorepo, and it provides features such as caching and parallel execution to speed up the build process.

fdm-docs/docs/contributing/02-setting-up-local-environment.md

@@ -0,0 +1,63 @@
+---
+title: Setting up Local Environment
+sidebar_label: Setting up Local Environment
+---
+
+This guide will walk you through the process of setting up a local development environment for the Farm Data Model (FDM) project.
+
+## Prerequisites
+
+Before you begin, you will need to have the following software installed on your machine:
+
+* **[Node.js](https://nodejs.org/en/download)**: FDM is a TypeScript and JavaScript project, so you will need to have Node.js installed.
+* **[`pnpm`](https://pnpm.io/installation)**: FDM uses `pnpm` for package management, so you will need to have it installed.
+* **[Git](https://git-scm.com/downloads)**: FDM is hosted on GitHub, so you will need to have Git installed to clone the repository.
+* **[Docker](https://docs.docker.com/get-docker/)**: FDM uses Docker to run the necessary services, such as the PostgreSQL database.
+
+## Cloning the Repository
+
+First, you need to clone the FDM repository from GitHub:
+
+```bash
+git clone https://github.com/SvenVw/fdm.git
+```
+
+## Installing Dependencies
+
+Next, you need to install the dependencies for all the packages in the monorepo. You can do this by running the following command from the root of the repository:
+
+```bash
+pnpm install
+```
+
+## Setting up `.env` files
+
+FDM uses `.env` files to manage environment variables. You will need to create a `.env` file in the `fdm-app` package. You can do this by copying the `.env.example` file:
+
+```bash
+cp fdm-app/.env.example fdm-app/.env
+```
+
+You will then need to fill in the values for the environment variables in the `.env` file.
+
+## Running Necessary Services
+
+FDM requires a PostgreSQL database to be running. The easiest way to do this is to use Docker. You can start the database by running the following command from the root of the repository:
+
+```bash
+docker-compose up -d
+```
+
+## External Services
+
+The `fdm-calculator` requires the `nmi-api` for Dutch nutrient advices. You can find the documentation for this API at [https://api.nmi-agro.nl/docs](https://api.nmi-agro.nl/docs). You need to have a NMI API key to access this service.
+
+## Running the Application
+
+Once you have completed all the previous steps, you can run the `fdm-app` by running the following command from the root of the repository:
+
+```bash
+pnpm --filter fdm-app dev
+```
+
+This will start the development server, and you should be able to access the application in your browser at `http://localhost:5173`.