Docs: improve coding guidelines

README.md

@@ -118,108 +118,3 @@ Start docker from 'support-services', and then in the project root folder :
 ```shell script
 npx nx e2e  (app_name)
 ```
-
-## Project structure
-
-The GeoNetwork UI project was generated using [Nx](https://nx.dev) and is composed of:
-
-- **libraries** containing components and services in the `libs` folder
-- **applications** using said components in the `apps` folder
-- **web components** using also said components in the `apps/webcomponents` folder
-
-Other directories include:
-
-- **conf**: configuration-related files
-- **translations**: contains the translations of all keys used in GeoNetwork UI
-- **tools**: various tools & utils for docker, internationalization etc.
-
-### Libraries
-
-Libraries are organized in the following fashion:
-
-1. Presentation libraries are in the `ui` folder and are categorized by their forms:
-
-   - `ui-inputs` for reusable components made to collect input from the user (e.g.: form fields, buttons...)
-   - `ui-elements` for components focused on rendering specific types of information in an elaborate way, which may or may not be related to business usages;
-     examples include download links, facet or selection tree, etc.
-   - `ui-layout` for components which occupy a large part of the screen and might contain variable content or other components
-   - `ui-map` for map-specific components (map container, controls, etc.)
-   - `ui-widgets` for reusable, small, self-contained components which show information in a visual way, similar to icons but more elaborate (e.g.: icon with tooltip, status indicator, progress bar...)
-
-   > Note: presentation components contain mainly HTML and CSS code, and should contain very little logic
-
-2. Libraries providing business or data logic and state management are in the `feature` folder and are categorized by their intended use:
-
-   - `feature-auth` for logic and components related to authentication
-   - `feature-catalog` for logic and components related to general catalog topics (title, logo, etc.)
-   - `feature-dataviz` for logic and components related to data visualization
-   - `feature-record` for logic and components related to displaying a catalog record's information (metadata, data preview, exports, APIs...)
-   - `feature-editor` for logic and components related to editing metadata
-   - `feature-map` for logic and components related to interactive maps
-   - `feature-search` for logic and components related to searching through the catalog
-   - `feature-notifications` for notifications systems
-
-   > Note: these libraries provide "smart components" which are communicating with each other using a NgRx store.  
-   > They rely on presentation components and as such hold very little HTML or CSS code.
-
-3. Libraries used for interacting with backend services are in the `data-access` folder:
-
-   - `data-access-gn4` contains an auto-generated API client for the GeoNetwork 4 backend
-   - `data-access-datafeeder` contains an auto-generated API client for the Datafeeder backend
-
-4. Libraries providing various utilities in the `util` folder:
-
-   - `util-data-fetcher` for fetching and querying datasets
-   - `util-app-config` for parsing and validating application configurations
-   - `util-shared` for shared models and types, test fixtures, app-wide settings etc.
-   - `util-i18n` for translation and internationalization
-
-5. Libraries providing common services or shared models are in the `util` folder:
-
-   - `common-domain` contains many definitions used across the whole project
-   - `common-fixtures` contains test fixtures
-
-6. Libraries providing low-level functionalities that can be used both in front and backend are in the `api` folder:
-   - `api-metadata-converter` for providing a pivot metadata model and conversion to interoperable formats
-
-#### `webcomponents`: Embeddable webcomponents
-
-See [the specific README file](apps/webcomponents).
-
-### Application Configuration
-
-GeoNetwork UI provides a standard way of configuring applications using the [conf/default.toml](conf/default.toml) file.
-
-This file can be used to:
-
-- customize the URL used to reach the GeoNetwork 4 API
-- indicate an optional proxy path to the application
-- indicate a metadata language to be used when searching
-- customize the theme used in the application (colors, fonts...)
-- define custom translations for the different languages
-
-Please refer to the embedded comments in the file for more information.
-
-> Note: as of now, only the Datahub application relies on this file
-
-**Important**: In order for the search to be efficient, please indicate the `metadata_language` of the queried catalog.
-
-### Internationalization
-
-Every label visible to the user in the different applications must be translated. All labels are identified using keys, for example:
-
-- `table.object.count`
-- `results.layout.selectOne`
-- `datafeeder.summarizePage.illustration`
-- `catalog.title.welcome.html`
-
-A repository of _all translations_ is available in the [translations](translations) folder. **These are the
-translations used in the different applications of the geonetwork-ui project.**
-
-> Please note that **only the translations whose key end in `.html`** can accept HTML markup.
-
-## To document
-
-How to build and run web components
-
-- Explain unit test setup & architecture with jest

docs/.vitepress/config.ts

@@ -10,11 +10,15 @@ export default defineConfig({
     nav: [
       { text: 'Guide', link: '/guide/introduction', activeMatch: '/guide/' },
       {
-        text: 'Reference',
-        link: '/reference/principles',
-        activeMatch: '/reference/',
+        text: 'For Developers',
+        link: '/developers/architecture-overview',
+        activeMatch: '/developers/',
       },
       { text: 'Applications', link: '/apps/datahub', activeMatch: '/apps/' },
+      {
+        text: 'Web Components',
+        link: 'https://github.com/geonetwork/geonetwork-ui/tree/main/apps/webcomponents',
+      },
       {
         text: `Version ${packageJson.version}`,
         link: 'https://github.com/geonetwork/geonetwork-ui/releases',
@@ -23,7 +27,7 @@ export default defineConfig({
 
     sidebar: {
       '/guide/': sidebarGuide(),
-      '/reference/': sidebarReference(),
+      '/developers/': sidebarForDevelopers(),
       '/apps/': sidebarApps(),
     },
 
@@ -73,46 +77,51 @@ function sidebarGuide() {
       ],
     },
     {
-      text: 'Contributing',
+      text: 'Reference',
       items: [
-        { text: 'Development environment', link: '/guide/dev-environment' },
-        { text: 'Create a Pull Request', link: '/guide/create-a-pr' },
-        { text: 'Code guide', link: '/guide/code-guide' },
-        { text: 'Versioning', link: '/guide/versioning' },
+        {
+          text: 'Supported search fields',
+          link: '/guide/search-fields',
+        },
       ],
     },
   ]
 }
 
-function sidebarReference() {
+function sidebarForDevelopers() {
   return [
     {
-      text: 'Architecture',
+      text: 'For developers',
       items: [
-        { text: 'Principles', link: '/reference/principles' },
-        { text: 'Internationalization', link: '/reference/i18n' },
-        { text: 'ElasticSearch index', link: '/reference/elasticsearch' },
-        { text: 'Organizations', link: '/reference/organizations' },
-        { text: 'State management', link: '/reference/state-management' },
-        { text: 'Routing', link: '/reference/routing' },
-        { text: 'Application configuration', link: '/reference/app-config' },
         {
-          text: 'Pivot Format',
-          link: '/reference/pivot-format',
+          text: 'Architecture overview',
+          link: '/developers/architecture-overview',
         },
+        { text: 'Application configuration', link: '/developers/app-config' },
+        { text: 'ElasticSearch index', link: '/developers/elasticsearch' },
+        { text: 'Internationalization', link: '/developers/i18n' },
+        { text: 'Interactive maps', link: '/developers/maps' },
+        { text: 'Organizations', link: '/developers/organizations' },
         {
-          text: 'Interactive maps',
-          link: '/reference/maps',
+          text: 'Pivot Format',
+          link: '/developers/pivot-format',
         },
+        { text: 'Routing', link: '/developers/routing' },
+        { text: 'State management', link: '/developers/state-management' },
+        { text: 'Testing', link: '/developers/testing' },
+        { text: 'Writing components', link: '/developers/writing-components' },
       ],
     },
     {
-      text: 'Web Components',
-      link: '/reference/webcomponents',
-    },
-    {
-      text: 'Supported search fields',
-      link: '/reference/search-fields',
+      text: 'Contributing',
+      items: [
+        {
+          text: 'Development environment',
+          link: '/developers/dev-environment',
+        },
+        { text: 'Create a Pull Request', link: '/developers/create-a-pr' },
+        { text: 'Versioning', link: '/developers/versioning' },
+      ],
     },
   ]
 }

docs/developers/app-config.md

@@ -0,0 +1,25 @@
+---
+outline: deep
+---
+
+# Application Configuration
+
+## Principle
+
+GeoNetwork UI provides a standard way of configuring applications using the [default.toml](https://github.com/geonetwork/geonetwork-ui/tree/main/conf/default.toml) file.
+
+This file can be used to:
+
+- customize the URL used to reach the GeoNetwork 4 API
+- indicate an optional proxy path to the application
+- indicate a metadata language to be used when searching
+- customize the theme used in the application (colors, fonts...)
+- define custom translations for the different languages
+
+Please refer to [the configuration guide](../guide/configure.md) as well as embedded comments in the file for more information.
+
+## The `util/app-config` library
+
+This library is the one which should be used when parsing a configuration file. Using a configuration file is not mandatory, each application can decide whether this is relevant.
+
+Only applications should rely on the `util/app-config` library! The other libraries should never assume that an application config is present, as this can very often not be the case (e.g. for web components).

docs/developers/architecture-overview.md

@@ -0,0 +1,101 @@
+---
+outline: deep
+---
+
+# Architecture overview
+
+The GeoNetwork UI project is a monorepo managed using [Nx](https://nx.dev) and is composed of:
+
+- **libraries** containing components and services in the `libs` folder
+- **applications** relying on libraries in the `apps` folder
+- **web components** relying on libraries in the `apps/webcomponents` folder
+
+Other directories include:
+
+- `assets-common`: shared assets across all apps
+- `conf`: configuration-related files
+- `docs`: this website
+- `package`: contains the necessary toolkit for generating the [NPM package](../guide/custom-app.md)
+- `support-services`: docker composition used to [set up the development environment](./dev-environment.md)
+- `tools`: various tools & utils for docker, internationalization etc.
+- `translations`: contains the translations of all keys used in the project
+
+## Libraries
+
+### Overview
+
+This is a general diagram of how libraries are organized:
+
+![architecture.svg](../assets/architecture.svg)
+<small>[Link to original drawing](https://excalidraw.com/#json=lOWFH0YhpcR39TMXGJ010,EbT5exajYjV0zcxEU5c4nw)</small>
+
+### Details
+
+The libraries are organized as follows:
+
+1. Presentation libraries are in the `ui` folder and are categorized by their forms:
+
+   - `ui-inputs` for reusable components made to collect input from the user (e.g.: form fields, buttons...)
+   - `ui-elements` for components focused on rendering specific types of information in an elaborate way, which may or may not be related to business usages;
+     examples include download links, facet or selection tree, etc.
+   - `ui-layout` for components which occupy a large part of the screen and might contain variable content or other components
+   - `ui-map` for map-specific components (map container, controls, etc.)
+   - `ui-widgets` for reusable, small, self-contained components which show information in a visual way, similar to icons but more elaborate (e.g.: icon with tooltip, status indicator, progress bar...)
+
+   > Note: presentation components contain mainly HTML and CSS code, and should contain very little logic
+
+2. Libraries providing business or data logic and state management are in the `feature` folder and are categorized by their intended use:
+
+   - `feature-auth` for logic and components related to authentication
+   - `feature-catalog` for logic and components related to general catalog topics (title, logo, etc.)
+   - `feature-dataviz` for logic and components related to data visualization
+   - `feature-record` for logic and components related to displaying a catalog record's information (metadata, data preview, exports, APIs...)
+   - `feature-editor` for logic and components related to editing metadata
+   - `feature-map` for logic and components related to interactive maps
+   - `feature-search` for logic and components related to searching through the catalog
+   - `feature-notifications` for notifications systems
+
+   > Note: these libraries provide "smart components" which are communicating with each other using a NgRx store.  
+   > They rely on presentation components and as such hold very little HTML or CSS code.
+
+3. Libraries used for interacting with backend services are in the `data-access` folder:
+
+   - `data-access-gn4` contains an auto-generated API client for the GeoNetwork 4 backend
+   - `data-access-datafeeder` contains an auto-generated API client for the Datafeeder backend
+
+4. Libraries providing various utilities in the `util` folder:
+
+   - `util-data-fetcher` for fetching and querying datasets
+   - `util-app-config` for parsing and validating application configurations
+   - `util-shared` for shared models and types, test fixtures, app-wide settings etc.
+   - `util-i18n` for translation and internationalization
+
+5. Libraries providing common services or shared models are in the `util` folder:
+
+   - `common-domain` contains many definitions used across the whole project
+   - `common-fixtures` contains test fixtures
+
+6. Libraries providing low-level functionalities that can be used both in front and backend are in the `api` folder:
+   - `api-repository` for providing the Records Repository abstraction as well as all models related to it (metadata records, etc.)
+   - `api-metadata-converter` for converting metadata from and to interoperable formats
+
+### Dependency constraints
+
+To ensure that the project structure stays healthy and avoid circular dependencies, several constraints dictating which kinds of libraries can depend on which were set up. These constraints are enforced by ESLint and configured in the [ESLint configuration file](https://github.com/geonetwork/geonetwork-ui/blob/main/.eslintrc.json).
+
+The constraints are:
+
+1. **No library should depend on `util/app-config`**  
+   This is because only applications should decide whether an app config file should be loaded (see [this page](./app-config.md) for more information).
+2. **Libraries of type `common`, `data-access` and `util` should only depend on libraries of the same type**
+3. **Libraries of type `ui` and `api` should only depend on _shared libraries_ or libraries of the same type**  
+   Shared libraries have the `scope:shared` tag; this is for instance the case for `util-i18n` and `util-shared`
+4. **Libraries of type `feature` can depend on any other kind of library** expect `util/app-config`
+
+## Web Components
+
+See [the specific README file](https://github.com/geonetwork/geonetwork-ui/tree/main/apps/webcomponents/README.md).
+
+## Applications
+
+See [the dedicated section of this website](../apps/datahub).

docs/reference/i18n.md → docs/developers/i18n.md

@@ -4,6 +4,20 @@ outline: deep
 
 # Internationalization
 
+Every label visible to the user in the different applications must be translated. All labels are identified using keys, for example:
+
+- `table.object.count`
+- `results.layout.selectOne`
+- `datafeeder.summarizePage.illustration`
+- `catalog.title.welcome.html`
+
+A repository of _all translations_ is available in the [translations](https://github.com/geonetwork/geonetwork-ui/tree/main/translations) folder. **These are the
+translations used in the different applications of the GeoNetwork-UI project.**
+
+::: info
+Please note that **only the translations whose key end in `.html`** can accept HTML markup.
+:::
+
 ## Language of the User Interface
 
 The User Interface supports translated labels and switching languages at runtime. The [`ngx-translate` library](https://github.com/ngx-translate/core) is used to handle all i18n aspects in GeoNetwork-UI.