docs: add Overview in Readme and package management explanation

README.md

@@ -5,6 +5,36 @@
 
 # DiracX-Web
 
+## Overview
+
+`diracx-web` is a web application that provides a user interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) service and is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem.
+
+This repository is organized as a monorepo, with the following key packages:
+
+- [diracx-web](packages/diracx-web)
+- [diracx-web-components](packages/diracx-web-components)
+- [diracx-web-extension-example](packages/diracx-web-extension-example)
+
+![Architecture diagram](docs/architecture_overview.png)
+
+### Packages
+
+- **DiracX-Web**: Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities.
+
+- **DiracX-Web-Components**: A library of reusable React components designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions.
+
+- **DiracX-Web-Extension-Example**: An illustrative example of a web extension demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package.
+
+### Project Management
+
+- **Lerna**: Utilized for efficient monorepo management. Useful to run scripts or commands across all packages while handling errors correctly.
+- **npm**: Used for dependency management.
+- **Release-Please**: Automated release management for the project.
+
+The dependency management is further detailed in the [Package Management](docs/package-management.md) documentation.
+
+For more detailed and interactive documentation, visit our [Storybook](https://diracgrid.github.io/diracx-web) instance.
+
 ## Getting started
 
 _Requirements: docker, internet_

docs/package-management.md

@@ -0,0 +1,28 @@
+# Package Management in the Monorepo
+
+## Using Local Packages
+
+When working on `diracx-web`, the monorepo configuration ensures that related packages (`diracx-web-components`) are automatically used from their local versions instead of fetching them from the npm registry. This setup allows developers to see the latest changes in real-time, so that any updates or modifications to these packages are immediately reflected in the `diracx-web` application during development.
+
+This approach streamlines the development process, reduces the need for frequent publishing to npm, and ensures consistency across the project.
+
+### Configuration
+
+Our monorepo is configured to use npm workspaces, which allows us to specify the projects and packages that should be linked locally.
+
+From the [npm documentation](https://docs.npmjs.com/cli/v10/using-npm/workspaces):
+
+> Workspaces is a generic term that refers to the set of features in the npm cli that provides support for managing multiple packages from your local file system from within a singular top-level, root package.
+>
+> This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. It automates the linking process as part of npm install and removes the need to manually use npm link in order to add references to packages that should be symlinked into the current node_modules folder.
+
+**Example `package.json` Configuration:**
+
+```json
+{
+  "workspaces": ["packages/diracx-web-components", "packages/diracx-web"]
+}
+```
+
+Note that any packages not listed in the `workspaces` (i.e. `diracx-web-extension-example` here) array are not considered workspaces. They will not be managed from the root of the monorepo and will not have access to the linked packages in the root `node_modules`, hence they will fetch them from the npm registry.
+Additionally, these packages will have their own `node_modules` folder.