docs: more docs restructure

Author: aldbr

README.md

@@ -7,6 +7,7 @@
 ![Unit tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/diracx-web-components-test.yml/badge.svg?branch=main)
 ![Integration tests](https://github.com/DIRACGrid/diracx-web/actions/workflows/diracx-web-test.yml/badge.svg?branch=main)
 ![Deployment](https://github.com/DIRACGrid/diracx-web/actions/workflows/deployment.yml/badge.svg?branch=main)
+![Gubbins](https://github.com/DIRACGrid/diracx-web/actions/workflows/gubbins-test.yml/badge.svg?branch=main)
 
 
 **DiracX-Web** is a web application that provides a user-friendly interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) services. It is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem.

docs/dev/manage_release.md …admin/explanations/manage_web_release.mddocs/dev/manage_release.md renamed to docs/admin/explanations/manage_web_release.md docs/dev/manage_release.md renamed to docs/admin/explanations/manage_web_release.md

@@ -3,7 +3,7 @@
 
 ### Development mode
 
-Refer to the [Developer Guide: Setting up you Development Environment](../developer/setup_environment.md) for instructions on running `diracx-web` in development mode.
+Refer to the [Developer Guide: Setting up your Development Environment](../../dev/how-to/setup_web_environment.md) for instructions on running `diracx-web` in development mode.
 
 ### Production mode
 
@@ -14,7 +14,8 @@ global.images.web.tag: <latest diracx-web version, docker tag>
 global.images.web.repository: <diracx-web docker image>
 ```
 
-:bulb: Make sure to update these values to point to the appropriate Docker image and version for your deployment.
+!!! tip
+    Make sure to update these values to point to the appropriate Docker image and version for your deployment.
 
 ### Integrating new features/hotfixes
 
@@ -25,14 +26,15 @@ diracxWeb.repoURL: <repository hosting the branch you want to apply>
 diracxWeb.branch: <branch hosting the changes you want to apply>
 ```
 
-:bulb: Make sure to update these values to point to the appropriate Docker image and version for your deployment.
+!!! tip
+    Make sure to update these values to point to the appropriate Docker image and version for your deployment.
 
 ## Extension
 
 
 ### `gubbins` extension in development mode
 
-For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../developer/manage_extension.md).
+For managing the `gubbins` extension in development mode, refer to the [Developer Guide: Managing an extension](../../dev/how-to/manage_web_extension.md).
 
 ### `gubbins` extension in development mode, as a standalone
 

docs/admin/deploy_instance.md docs/admin/how-to/deploy_web_instance.mddocs/admin/deploy_instance.md renamed to docs/admin/how-to/deploy_web_instance.md

@@ -0,0 +1,35 @@
+# Contributing to DiracX-Web
+
+*Requirements: [Setup Environment](setup_web_environment.md)*
+
+=== "Documentation"
+
+    Ensure that any code you write is well-documented. This includes:
+
+    - Inline comments where necessary to explain complex logic.
+    - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library.
+    - You can use tools like [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to maintain code quality.
+
+=== "Testing"
+
+    **Component Testing**
+    : Write tests for your stories to ensure they work as expected. Use [Jest](https://jestjs.io/) for unit testing and snapshot testing of your React components.
+
+    **Application Testing**
+    : Use [Cypress](https://www.cypress.io/) for end-to-end testing to simulate real user interactions and ensure your application behaves correctly.
+
+    **Test Coverage**
+    : Maintain good test coverage to ensure that your critical features are well-protected during updates. Tools like Jest provide [coverage reports](https://jestjs.io/docs/code-coverage) that help you identify untested parts of your code.
+
+=== "Accessibility"
+
+    Make your application accessible to all users. Use semantic HTML, ARIA attributes, and test your application with different screen sizes and assistive technologies.
+
+!!! note
+    If you create an export function or component in `diracx-web-components`, you must add it to the `index.ts` file and run `npm run build` inside `packages/diracx-web-components` to ensure the pre-commit hook passes.
+
+!!! warning
+    Don't forget to update the `packages/extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](manage_web_extension.md) for further details.
+
+!!! note "Pre-commit Hooks"
+    `Husky` is configured to run as a pre-commit script, executing tasks such as linting staged files to maintain code consistency with the codebase.

docs/dev/how-to/contribute_to_web.md

@@ -14,12 +14,14 @@ You must provide:
 - An icon that will appear in the `Add application` menu
 - An optional function, `validateAndConvertState`, which identifies and corrects the structure of a JSON pasted by the user during import. This function ensures compatibility between versions by transforming the pasted state into a valid, updated version. It should be reviewed and updated in any version that modifies the exported/imported state structure
 
-💡You can look at the type `ApplicationMetadata` for more details
+!!! tip
+    You can look at the type `ApplicationMetadata` for more details.
 
 ### Code the application
 
 The code of your app should be in `packages/diracx-web-components/src/components/<new-app>`. The new app can and should use what already exist in `@dirac-grid/diracx-web-components`. 
 
 In order to be compatible with the share and import buttons, the application must write its state to the session storage at `<appId>_State`. This slot is read from and written to by the corresponding functions.
 
-💡You can look at `JobMonitor` as an example.
+!!! tip
+    You can look at `JobMonitor` as an example.

docs/dev/how-to/create_application.md docs/dev/how-to/create_web_application.mddocs/dev/how-to/create_application.md renamed to docs/dev/how-to/create_web_application.md

@@ -81,8 +81,5 @@ export DIRACX_URL=<diracX installation>
 npm run --prefix packages/extensions test
 ```
 
-### `gubbins` (backend)
-
-Follow the instructions from the [Gubbins extension README](https://github.com/DIRACGrid/diracx/tree/main/extensions#work-on-gubbins).
-
-:bulb: Like `diracx-web`, `gubbins-web` does automatically reflect changes made in `diracx-web-components`. This means that while running `gubbins` using `diracx-charts/run_demo.sh`, any modifications to `diracx-web-components` will also be applied to `gubbins`.
+!!! tip
+    Like `diracx-web`, `gubbins-web` does automatically reflect changes made in `diracx-web-components`. This means that while running `gubbins` using `diracx-charts/run_demo.sh`, any modifications to `diracx-web-components` will also be applied to `gubbins`.

docs/dev/manage_extension.md docs/dev/how-to/manage_web_extension.mddocs/dev/manage_extension.md renamed to docs/dev/how-to/manage_web_extension.md

@@ -140,7 +140,8 @@ git clone git@github.com:DIRACGrid/diracx-charts.git
 diracx-charts/run_demo.sh ./diracx-web [./diracx]
 ```
 
-:bulb: Any change made in `diracx-web-components` are automatically reflected into the development environment. We rely on the [NextJS transpile option](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages). Further details are available in the `diracx-web` NextJS configuration.
+!!! tip
+    Any change made in `diracx-web-components` is automatically reflected into the development environment. We rely on the [NextJS transpile option](https://nextjs.org/docs/app/api-reference/config/next-config-js/transpilePackages). Further details are available in the `diracx-web` NextJS configuration.
 
 ## Testing
 

docs/dev/setup_environment.md docs/dev/how-to/setup_web_environment.mddocs/dev/setup_environment.md renamed to docs/dev/how-to/setup_web_environment.md

@@ -0,0 +1,74 @@
+# Web Architecture
+
+## Monorepo Structure
+
+The DiracX-Web repository is organized as a monorepo using [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces). Local packages are resolved from their workspace versions rather than the npm registry.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TD
+ subgraph monorepo["Monorepo"]
+        components["diracx-web-components"]
+        web["diracx-web"]
+        extensions["extensions (gubbins)"]
+  end
+    web -. uses .-> components
+    extensions -. uses .-> components
+    components -- published on --> npm["npm registry"]
+    community["Community extensions"] -. uses .-> npm
+```
+
+## Packages
+
+### diracx-web-components
+
+- **Purpose**: Reusable React component library.
+- **Build tool**: [tsup](https://tsup.egoist.dev/) for TypeScript compilation.
+- **Design system**: [Material-UI (MUI)](https://mui.com/).
+- **Documentation**: [Storybook](https://storybook.js.org/).
+- **Testing**: [Jest](https://jestjs.io/) + [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).
+- **Exports**: Components, contexts, hooks, and types as separate modules.
+
+### diracx-web
+
+- **Purpose**: Vanilla DiracX web interface.
+- **Framework**: [Next.js 15](https://nextjs.org/) with App Router.
+- **Output**: Static export (`output: "export"`).
+- **Authentication**: [@axa-fr/react-oidc](https://github.com/AxaFrance/oidc-client).
+- **Testing**: [Cypress](https://www.cypress.io/) for end-to-end tests.
+- **Serving**: Nginx in production (Docker image).
+
+### extensions (gubbins)
+
+- **Purpose**: Reference example of a custom DiracX web extension.
+- **Framework**: Next.js, same setup as `diracx-web`.
+- **Demonstrates**: How to extend the application list, add custom components, and deploy as a standalone project.
+
+## Key Directories
+
+| Path | Description |
+|---|---|
+| `packages/diracx-web-components/src/components/` | Reusable UI components |
+| `packages/diracx-web-components/src/contexts/` | React contexts for state management |
+| `packages/diracx-web-components/src/hooks/` | Custom React hooks |
+| `packages/diracx-web-components/src/types/` | TypeScript type definitions |
+| `packages/diracx-web/src/app/` | Next.js App Router pages and layouts |
+| `packages/extensions/src/` | Extension source (gubbins example) |
+
+## Routing
+
+DiracX-Web uses [Next.js folder-based routing](https://nextjs.org/docs/app/building-your-application/routing):
+
+- `src/app/(dashboard)/` — Main dashboard (parentheses are ignored in the route, so this is the root URL).
+- `src/app/auth/` — Authentication pages, served at `/auth`.
+- `page.tsx` files define the UI for a route.
+- `layout.tsx` files define shared UI for a segment and its children.
+
+## State Management
+
+- **Application state**: Managed via React Context (`ApplicationProvider`).
+- **Session storage**: Each application instance writes its state to `<appId>_State` for share/import functionality.
+- **URL encoding**: Dashboard layout is encoded in the URL for sharing.