docs: update diracx-web documentation (DIRACGrid#803)

aldbr · mezzeddine · commit 4e0e4e0384e8 · 2026-02-27T08:47:58.000+01:00
diff --git a/docs/dev/explanations/extensions.md b/docs/dev/explanations/extensions.md
@@ -30,7 +30,7 @@ Okay, so you've decided you definitely do need an extension but not all extensio
 Before proceeding you should read and and understand the [structure of DiracX](./components/index.md) to know which components you want to extend.
 For most components you can extend them in isolation without needing to have an extension for the other components, for example:
 
-- `diracx-web` can be extended to customize the web interface without needing to extend any of the Python packages.
+- `diracx-web` can be extended to customize the web interface without needing to extend any of the Python packages. For details, see the [Creating a web extension](../tutorials/web-extensions.md) tutorial.
 - `diracx-logic` can be extended without needing to extend `diracx-core` or `diracx-routers`
 
 The exception to this is when extending `diracx-routers` you MUST also extend `diracx-client` and your client extension MUST be regenerated for every DiracX release.
diff --git a/docs/dev/explanations/repo-structure.md b/docs/dev/explanations/repo-structure.md
@@ -0,0 +1,112 @@
+# Repository Structure
+
+DiracX is developed across three repositories, each with a distinct responsibility. They are combined into a single documentation site and a single deployment, but developed independently.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+flowchart TD
+ subgraph diracx["diracx (Python)"]
+    direction TB
+    subgraph backend["Backend"]
+            core["diracx-core"]
+            db["diracx-db"]
+            logic["diracx-logic"]
+            routers["diracx-routers"]
+            tasks["diracx-tasks"]
+      end
+    subgraph frontend-py["Frontend (CLI)"]
+            client["diracx-client"]
+            api["diracx-api"]
+            cli["diracx-cli"]
+      end
+  end
+ subgraph diracx-web["diracx-web (TypeScript)"]
+    direction TB
+    subgraph frontend-web["Frontend (Web)"]
+            components["diracx-web-components"]
+            app["diracx-web app"]
+            extensions["extensions (gubbins)"]
+      end
+  end
+ subgraph diracx-charts["diracx-charts (Helm)"]
+    direction TB
+        charts["Helm charts"]
+        demo["run_demo.sh"]
+  end
+    routers -- serves API --> client
+    client -. "calls through OpenAPI" .-> routers
+    charts -. deploys .-> diracx
+    charts -. deploys .-> diracx-web
+    app -. "calls through OpenAPI" .-> routers
+
+     core:::Pine
+     db:::Pine
+     logic:::Pine
+     routers:::Pine
+     tasks:::Pine
+     client:::Sky
+     api:::Sky
+     cli:::Sky
+     components:::Rose
+     app:::Rose
+     extensions:::Rose
+     charts:::Aqua
+     demo:::Aqua
+    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF
+    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
+    classDef Rose stroke-width:1px, stroke-dasharray:none, stroke:#FF5978, fill:#FFDFE5, color:#8E2236
+    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
+```
+
+## Repositories
+
+### [`diracx`](https://github.com/DIRACGrid/diracx)
+
+The main repository containing all Python packages. It holds both **backend** (server-side) and **frontend CLI** (client-side) code:
+
+- **Backend** — `diracx-core`, `diracx-db`, `diracx-logic`, `diracx-routers`, `diracx-tasks`: the server that exposes an OpenAPI-based REST API.
+- **Frontend (CLI)** — `diracx-client`, `diracx-api`, `diracx-cli`: the Python client, higher-level API, and command-line interface that consume the REST API.
+
+This repository also owns the `mkdocs.yml` that defines the navigation for the entire documentation site.
+
+### [`diracx-web`](https://github.com/DIRACGrid/diracx-web)
+
+The web interface, built with TypeScript / React / Next.js. It is a separate frontend that also consumes the REST API served by `diracx-routers`. See [Web architecture](web-architecture.md) for the internal package structure.
+
+Documentation files in this repo are merged into the main site by the [mkdocs-diracx-plugin](https://github.com/DIRACGrid/mkdocs-diracx-plugin). See [Documentation system](documentation-system.md) for details on how the merge works.
+
+### [`diracx-charts`](https://github.com/DIRACGrid/diracx-charts)
+
+Helm charts for deploying DiracX (backend + web) on Kubernetes. Also provides `run_demo.sh` for running a local development instance. Documentation files are similarly merged into the main site.
+
+## What "Backend" and "Frontend" mean in this project
+
+The terms follow standard software architecture usage:
+
+- **Backend** = server-side code that processes requests, accesses databases, and enforces business logic.
+- **Frontend** = client-side code that users interact with to consume backend services.
+
+DiracX has two frontends:
+
+| Frontend | Language   | Repository   | Interface                              |
+| -------- | ---------- | ------------ | -------------------------------------- |
+| **CLI**  | Python     | `diracx`     | Command-line + programmatic Python API |
+| **Web**  | TypeScript | `diracx-web` | Browser-based graphical interface      |
+
+Both communicate with the backend through the same OpenAPI-based REST API.
+
+## Where to make changes
+
+| I want to...                    | Repository      | Relevant docs                                                  |
+| ------------------------------- | --------------- | -------------------------------------------------------------- |
+| Add or modify a REST endpoint   | `diracx`        | [Add a route](../how-to/add-a-route.md)                        |
+| Add or modify business logic    | `diracx`        | [Designing functionality](designing-functionality.md)          |
+| Add or modify a database        | `diracx`        | [Add a DB](../how-to/add-a-db.md)                              |
+| Add or modify a CLI command     | `diracx`        | [Add a CLI command](../how-to/add-a-cli-command.md)            |
+| Add or modify the web interface | `diracx-web`    | [Getting started (web)](../tutorials/web-getting-started.md)   |
+| Create a web extension          | `diracx-web`    | [Creating a web extension](../tutorials/web-extensions.md)     |
+| Change deployment / Helm values | `diracx-charts` | [Chart structure](../../admin/explanations/chart-structure.md) |
+| Run the demo locally            | `diracx-charts` | [Run demo](run_demo.md)                                        |
diff --git a/docs/dev/how-to/contribute.md b/docs/dev/how-to/contribute.md
@@ -19,16 +19,9 @@
 
 === "DiracX Web"
 
-    **Requirements:** [Getting Started](../tutorials/getting-started.md)
-
-    - **Code 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.
-
-    - **Writing/Updating Tests:** When you change or add new code, make sure to write or update tests accordingly. This helps maintain the reliability and stability of the codebase.
+    **Requirements:** [Setup web environment](setup-web-environment.md)
 
-    **Note:** Don't forget to update the `extensions` code if you integrate breaking changes in the `diracx-web-components` library. See [Managing the extension](../setup_environment.md) for further details.
+    For web-specific contribution guidelines (code documentation, testing, accessibility, Husky hooks), see the [DiracX Web contribution guide](contribute-to-web.md).
 
 ### 3. Commit
 
diff --git a/docs/dev/how-to/write-docs.md b/docs/dev/how-to/write-docs.md
diff --git a/docs/dev/reference/index.md b/docs/dev/reference/index.md
@@ -0,0 +1,31 @@
+# Reference
+
+Technical reference material for DiracX developers.
+
+## General
+
+- [Coding conventions](coding-conventions.md)
+- [Writing tests](writing-tests.md)
+- [Test recipes](test-recipes.md)
+- [Pixi tasks](pixi-tasks.md)
+- [Dev env variables](env-variables.md)
+
+## Backend
+
+- [Configuration](configuration.md)
+- [Dependency injection](dependency-injection.md)
+- [Application state](application-state.md)
+- [DB transaction model](db-transaction-model.md)
+- [Entrypoints](entrypoints.md)
+- [Security policies](security-policies.md)
+- [Security properties](security-properties.md)
+
+## Frontend
+
+### CLI
+
+- [Client metapathfinder](client-metapathfinder.md)
+
+### Web
+
+- [Coding conventions](web-coding-conventions.md)
diff --git a/docs/dev/tutorials/develop-web.md b/docs/dev/tutorials/develop-web.md
diff --git a/docs/dev/tutorials/index.md b/docs/dev/tutorials/index.md
@@ -0,0 +1,19 @@
+# Tutorials
+
+Step-by-step guides to help you get started with DiracX development.
+
+## Backend
+
+- [Getting started](getting-started.md) — Set up your development environment and run DiracX locally
+- [Larger developments](larger-developments.md) — Working on bigger changes
+- [Advanced tutorial](advanced-tutorial.md) — Deeper dive into DiracX internals
+- [Making changes](making-changes.md) — How to make and test changes
+- [Run a full DiracX instance locally](run-locally.md) — Deploy the full stack on your machine
+- [Play with auth](play-with-auth.md) — Explore the authentication system
+
+## Frontend
+
+### Web
+
+- [Getting started](web-getting-started.md) — Set up the web development environment
+- [Creating a web extension](web-extensions.md) — Build a custom DiracX web extension
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -59,19 +59,18 @@ nav:
     - Tutorials:
       - user/tutorials/index.md
     - How-To:
-      - user/how-to/index.md
+      - Command Line: user/reference/programmatic-usage/command-line-interface.md
+      - Programmatic Usage:
+        - user/reference/programmatic-usage/index.md
+        - Python: user/reference/programmatic-usage/python-interface.md
+        - HTTPS: user/reference/programmatic-usage/https-interface.md
+      - Web Interface:
+        - user/how-to/index.md
+        - Logging in: user/how-to/login-out.md
+        - List and share applications: user/how-to/list-and-share-applications.md
+        - Monitor jobs: user/how-to/monitor-jobs.md
     - Explanations:
       - user/explanations/index.md
-    - Web:
-      - user/web/index.md
-      - Logging in: user/web/login_out.md
-      - List and share applications: user/web/list_and_share_applications.md
-      - Monitor jobs: user/web/monitor_jobs.md
-    - Programmatic Usage:
-      - user/reference/programmatic-usage/index.md
-      - Command Line: user/reference/programmatic-usage/command-line-interface.md
-      - Python: user/reference/programmatic-usage/python-interface.md
-      - HTTPS: user/reference/programmatic-usage/https-interface.md
     - Reference:
       - user/reference/index.md
       - Client Config: user/reference/client-configuration.md
@@ -103,6 +102,7 @@ nav:
       - Chart structure: admin/explanations/chart-structure.md
       - Databases: admin/explanations/database-management.md
       - Sandbox Store: admin/explanations/sandbox-store.md
+      - Web release process: admin/explanations/manage-web-release.md
     - Tutorials:
       - admin/tutorials/index.md
       - Authentication: admin/tutorials/authentication.md
@@ -117,76 +117,91 @@ nav:
 
   - Developer Guide:
     - dev/index.md
-    - Getting started: dev/tutorials/getting-started.md
     - Tutorials:
       - dev/tutorials/index.md
-      - Larger developments: dev/tutorials/larger-developments.md
-      - Advanced tutorial: dev/tutorials/advanced-tutorial.md
-      - Making changes: dev/tutorials/making-changes.md
-      - Developing DiracX Web: dev/tutorials/develop-web.md
-      - Run a full DiracX instance locally: dev/tutorials/run-locally.md
-      - Play with auth: dev/tutorials/play-with-auth.md
+      - Backend:
+          - Getting started: dev/tutorials/getting-started.md
+          - Larger developments: dev/tutorials/larger-developments.md
+          - Advanced tutorial: dev/tutorials/advanced-tutorial.md
+          - Making changes: dev/tutorials/making-changes.md
+          - Run a full DiracX instance locally: dev/tutorials/run-locally.md
+          - Play with auth: dev/tutorials/play-with-auth.md
+      - Frontend:
+          - Web:
+              - Getting started: dev/tutorials/web-getting-started.md
+              - Creating a web extension: dev/tutorials/web-extensions.md
     - How-To:
       - dev/how-to/index.md
       - Contribute: dev/how-to/contribute.md
-      - Write docs: dev/tutorials/write-docs.md
-      - Add functionality:
-        - dev/how-to/add-functionality/index.md
-        - New route or router: dev/how-to/add-a-route.md
-        - New task: dev/how-to/add-a-task.md
-        - New DB: dev/how-to/add-a-db.md
-        - New CLI command: dev/how-to/add-a-cli-command.md
-        - New settings: dev/how-to/add-a-setting.md
-        - Add a test: dev/how-to/add-a-test.md
-      - Extend DiracX:
-        - dev/how-to/extend-diracx/index.md
-      - Develop legacy DIRAC: dev/how-to/develop-legacy-dirac.md
+      - Write docs: dev/how-to/write-docs.md
       - Use the demo:
         - dev/how-to/use-the-demo/index.md
         - Accessing the client: dev/how-to/use-the-demo/swagger.md
-        - Use swagger: dev/how-to/use-the-demo/swagger.md
         - Accessing DiracX Web: dev/how-to/use-the-demo/web.md
-      - Client customization: dev/how-to/client-customization.md
-      - Client generation: dev/how-to/client-generation.md
-      - Client extensions: dev/how-to/client-extension.md
-    - Web Development:  # TODO: These should move to fit into the new unified structure
-      - Setup environment: dev/setup_environment.md
-      - Manage extensions: dev/manage_extension.md
-      - Web architecture: dev/web-arch.md
-      - Create application: dev/how-to/create_application.md
-      - Setup: developer/setup_environment.md
-      - Contribute: developer/contribute.md
-      - Manage extensions: developer/manage_extension.md
+      - Backend:
+        - Add functionality:
+          - dev/how-to/add-functionality/index.md
+          - New route or router: dev/how-to/add-a-route.md
+          - New task: dev/how-to/add-a-task.md
+          - New DB: dev/how-to/add-a-db.md
+          - New settings: dev/how-to/add-a-setting.md
+          - Add a test: dev/how-to/add-a-test.md
+        - Extend DiracX:
+          - dev/how-to/extend-diracx/index.md
+        - Develop legacy DIRAC: dev/how-to/develop-legacy-dirac.md
+      - Frontend:
+        - CLI:
+          - New CLI command: dev/how-to/add-a-cli-command.md
+          - Client customization: dev/how-to/client-customization.md
+          - Client generation: dev/how-to/client-generation.md
+          - Client extensions: dev/how-to/client-extension.md
+        - Web:
+          - Contribute to web: dev/how-to/contribute-to-web.md
+          - Setup web environment: dev/how-to/setup-web-environment.md
+          - Create a web application: dev/how-to/create-web-application.md
+          - Manage web extensions: dev/how-to/manage-web-extension.md
     - Explanations:
       - dev/explanations/index.md
+      - Repository structure: dev/explanations/repo-structure.md
       - Documentation system: dev/explanations/documentation-system.md
-      - Components:
-        - dev/explanations/components/index.md
-        - API: dev/explanations/components/api.md
-        - CLI: dev/explanations/components/cli.md
-        - Databases: dev/explanations/components/db.md
-        - Routes: dev/explanations/components/routes.md
-        - Client: dev/explanations/components/client.md
-      - Testing: dev/explanations/testing.md
-      - Run demo: dev/explanations/run_demo.md
-      - Extensions: dev/explanations/extensions.md
-      - Designing functionality: dev/explanations/designing-functionality.md
+      - Components overview: dev/explanations/components/index.md
       - Dependency management: dev/explanations/dependency-management.md
+      - Run demo: dev/explanations/run_demo.md
+      - Backend:
+          - Components:
+              - Databases: dev/explanations/components/db.md
+              - Routes: dev/explanations/components/routes.md
+          - Testing: dev/explanations/testing.md
+          - Extensions: dev/explanations/extensions.md
+          - Designing functionality: dev/explanations/designing-functionality.md
+      - Frontend:
+          - CLI:
+              - API: dev/explanations/components/api.md
+              - CLI: dev/explanations/components/cli.md
+              - Client: dev/explanations/components/client.md
+          - Web:
+              - Architecture: dev/explanations/web-architecture.md
+              - Testing: dev/explanations/web-testing.md
     - Reference:
       - dev/reference/index.md
-      - Dev env variables: dev/reference/env-variables.md
-      - Writing tests: dev/reference/writing-tests.md
       - Coding conventions: dev/reference/coding-conventions.md
-      - Configuration: dev/reference/configuration.md
-      - Dependency injection: dev/reference/dependency-injection.md
-      - Application state: dev/reference/application-state.md
-      - Client metapathfinder: dev/reference/client-metapathfinder.md
-      - DB transaction model: dev/reference/db-transaction-model.md
-      - Entrypoints: dev/reference/entrypoints.md
-      - Pixi tasks: dev/reference/pixi-tasks.md
-      - Security policies: dev/reference/security-policies.md
-      - Security properties: dev/reference/security-properties.md
+      - Writing tests: dev/reference/writing-tests.md
       - Test recipes: dev/reference/test-recipes.md
+      - Pixi tasks: dev/reference/pixi-tasks.md
+      - Dev env variables: dev/reference/env-variables.md
+      - Backend:
+          - Configuration: dev/reference/configuration.md
+          - Dependency injection: dev/reference/dependency-injection.md
+          - Application state: dev/reference/application-state.md
+          - DB transaction model: dev/reference/db-transaction-model.md
+          - Entrypoints: dev/reference/entrypoints.md
+          - Security policies: dev/reference/security-policies.md
+          - Security properties: dev/reference/security-properties.md
+      - Frontend:
+          - CLI:
+              - Client metapathfinder: dev/reference/client-metapathfinder.md
+          - Web:
+              - Coding conventions: dev/reference/web-coding-conventions.md
 
 markdown_extensions:
   - admonition
