diff --git a/.github/instructions/copilot-instructions.md b/.github/copilot-instructions.md similarity index 97% rename from .github/instructions/copilot-instructions.md rename to .github/copilot-instructions.md index 9300ecc..b085feb 100644 --- a/.github/instructions/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -100,4 +100,4 @@ import { UserStatusGate } from 'src/components'; ## References - [Architecture Blueprint](../../docs/architecture/Project_Architecture_Blueprint.md) - [Conventional Commits](../../docs/coding-rules/conventional-commits.md) -- [Admin Portal Overview](../../docs/functional/00%203%20Admin%20Portal%20Overview.md) +- [Admin Portal Overview](../../docs/functional/00 3 Admin Portal Overview.md) diff --git a/docs/architecture/V5/API v5.md b/docs/architecture/V5/API v5.md deleted file mode 100644 index bd4f14e..0000000 --- a/docs/architecture/V5/API v5.md +++ /dev/null @@ -1,9 +0,0 @@ - - - -The data (organizations, solutions, workspaces) is provided by the Cosmo Tech API. We will use the v5 of the API. - -The portal admin uses the official TypeScript client library: [@cosmotech/api-ts] -https://www.npmjs.com/package/@cosmotech/api-ts/v/5.0.0-rc5 . - -The diff --git a/docs/functional/00 1 Platform Portal Requirements.md b/docs/functional/00 1 Platform Portal Requirements.md deleted file mode 100644 index 07107d2..0000000 --- a/docs/functional/00 1 Platform Portal Requirements.md +++ /dev/null @@ -1,11 +0,0 @@ - - - -The Cosmo Tech "Platform Portal" is a set of tools and services that allow platform administrators to manage and configure the Cosmo Tech platform. The Platform Portal provides capabilities for overseeing multiple organizations, managing global settings, and ensuring compliance across the platform. - -The first module is the "Admin Portal", which is a web-based interface designed for administrators to manage and oversee various aspects of the Cosmo Tech platform. It provides an intuitive and user-friendly environment for configuring the objects used by the Cosmo Tech platform: - -- organizations -- solutions -- workspaces -- runners diff --git a/docs/functional/00 3 Admin Portal Overview.md b/docs/functional/00 3 Admin Portal Overview.md deleted file mode 100644 index 00ad12a..0000000 --- a/docs/functional/00 3 Admin Portal Overview.md +++ /dev/null @@ -1,50 +0,0 @@ - - - -# Admin Portal Overview - -The "Admin Portal" is a web-based interface designed for administrators to manage and oversee various aspects of the Cosmo Tech platform. It provides an intuitive and user-friendly environment for configuring the objects used by the Cosmo Tech platform: - -- organizations -- solutions -- workspaces -- runners -- runs - -Mock-ups -You can find the mock-ups for the Admin Portal [here](https://www.figma.com/proto/Wna4gI78OCyHc0rO2V1qNq/Admin-Portal) -They are downloaded locally in the repository under docs/mock-ups/ - -# Multi API and Multi Auth - -The Admin Portal supports 2 major API versions : API v3 and API v5. - -Authentication Provider -The Admin Portal supports 2 authentication providers : Azure for API v3 and Keycloak for API v5. - -# Core Concepts in API v5 - -## Organizations - -Simulation Digital Twin Organizations are logical groups of platform resources securely isolated from one another within the same cloud tenant and subscription. An Organization defines a company or legal entity and can contain resources for multiple Solutions. It serves as the core of multi-tenant security and manages the hierarchy of workspaces and solutions. User permissions are managed at this level using access-control lists (ACL) with roles such as Viewer, User, Editor, and Admin. - -## Solutions - -A Simulation Digital Twin Solution is software supporting decision-making that provides projections of strategy outcomes using a digital representation of the system and its dynamics. From a developer's perspective, a solution combines the source code of a simulator with at least one run template. It defines the parameters available for a scenario, how to validate a model, and how to execute the engine. Solutions are configured using JSON or YAML files to declare elements such as run templates and parameter groups. - -## Workspaces - -A Workspace defines an analysis or project space that is bound to a Solution. It contextualises business use cases with a web application, dashboard definitions, and available run templates. Workspaces contain Scenarios and require dedicated Azure resources, such as Azure Digital Twins, Event Hubs, or Azure Data Explorer, to function properly. Access permissions are enforced at the workspace level, requiring users to be added to the security list to read workspace resources. - -## Runners - -A Runner is a component hierarchically situated under a workspace that allows the execution of run templates, such as ETL scripts. To create a valid runner, one must reference a valid dataset, a run template defined in the Solution object, and define security access. Access to runners requires specific permissions, needing at least viewer rights on the organization and user rights on the workspace containing the runner. - -## Runs - -A Run (or Scenario Run) is the execution of a scenario. It combines a Dataset with a Run type within the context of a Simulator to perform the necessary computations. The run produces simulation results, which are projections of the system's state over a defined period used to compute KPIs. A run can have a status of Successful, Running, Pending (scheduled but blocked by resource unavailability), or Failed. - -# Core Concepts in API v3 - -Starting with version v3.3, the concepts are similar to API v5. -TODO : mark any notable differences here diff --git a/docs/functional/Mock-ups/Mock-up figma_export_1.png b/docs/functional/Mock-ups/Mock-up figma_export_1.png deleted file mode 100644 index 95f17e0..0000000 Binary files a/docs/functional/Mock-ups/Mock-up figma_export_1.png and /dev/null differ diff --git a/docs/functional/Mock-ups/Mock-up figma_export_2.png b/docs/functional/Mock-ups/Mock-up figma_export_2.png deleted file mode 100644 index 1bf546a..0000000 Binary files a/docs/functional/Mock-ups/Mock-up figma_export_2.png and /dev/null differ diff --git a/docs/plan/00-login-plan.md b/docs/plan/00-login-plan.md new file mode 100644 index 0000000..71d6b36 --- /dev/null +++ b/docs/plan/00-login-plan.md @@ -0,0 +1,58 @@ + + +# Login Flow Technical Design + +## Overview + +Design the login flow with tenant selection, dynamic TypeScript client instantiation (v3 or v5), tenant persistence in localStorage, and automatic redirect to the first organization's detail view. + +## Steps + +### 1. Add API Version Detection + +**File:** `src/services/api/apiUtils.js` + +Enhance `detectApiAuthProviderType` to also return API version by parsing the `COSMOTECH_API_PATH` URL (e.g., `/v3` → `'v3'`, `/v5` → `'v5'`). Add new function `detectApiVersion(api)`. + +### 2. Refactor API Client for Dynamic Version + +**File:** `src/services/api/apiClient.js` + +Refactor `getApiClient` to accept a version parameter and dynamically import from either `@cosmotech/api-ts-v3` or `@cosmotech/api-ts-v5` based on detected version. + +### 3. Persist Selected Tenant + +**File:** `src/services/api/apiManager.js` + +Update `apiManager` to persist selected tenant via `localStorage.setItem('selectedApi', apiName)` on selection, and restore it on app initialization in the constructor. + +### 4. Extend Login Thunk + +**File:** `src/state/auth/thunks/login.js` + +After successful auth: +- Dispatch `getAllOrganizations()` +- Store `apiVersion` and first `organizationId` in Redux state +- Navigate to `/organization/{firstOrgId}` using React Router + +### 5. Update Login View + +**File:** `src/views/Login.jsx` + +Show loading state during org fetch and handle the redirect after organizations are loaded. + +### 6. Add Redux State Fields + +**File:** `src/state/auth/reducers.js` + +Add to auth slice: +- `selectedApiVersion: 'v3' | 'v5' | null` +- `selectedOrganizationId: string | null` + +## Considerations + +1. **Dynamic import strategy:** Use `await import('@cosmotech/api-ts-v5')` for lazy loading, or pre-import both and switch at runtime? Recommend dynamic import to reduce bundle size. + +2. **Error case:** If organization list is empty after login, redirect to an error/empty state page rather than crashing. + +3. **Session restore:** On page refresh, restore both tenant AND navigate back to last organization if `selectedOrganizationId` is persisted. diff --git a/docs/requirements/00 core requirements/01-Platform Portal Requirements.md b/docs/requirements/00 core requirements/01-Platform Portal Requirements.md new file mode 100644 index 0000000..a3b96f5 --- /dev/null +++ b/docs/requirements/00 core requirements/01-Platform Portal Requirements.md @@ -0,0 +1,115 @@ + + +# **Cosmo Tech Platform Portal: Requirements** + +## **1. Introduction** + +The Cosmo Tech **Platform Portal** is a centralized suite of services for platform administrators. It is designed to oversee multiple organizations, manage global configurations, and ensure compliance. + +The primary module is the **Admin Portal**, a web-based interface that provides an intuitive environment for managing the lifecycle of Cosmo Tech platform objects. + +## **2. Platform Architecture & Multi-API Support** + +The Admin Portal must act as a bridge between two distinct generations of the Cosmo Tech API, handling the transition between cloud-native and on-premise environments. + +### **2.1 API Versions** + +| **Feature** | **API v3** | **API v5** | +| :---: | :---: | :---: | +| **Deployment** | Azure (Cloud) | On-Premise / Self-Hosted | +| **Auth Provider** | Azure Active Directory (Microsoft Entra ID) | **Keycloak** | +| **Primary Objects** | Organizations, Solutions, Workspaces, Scenarios… | Organizations, Solutions, Workspaces, Runners, Runs | + +### **2.2 Unified Authentication Flow** + +The Admin Portal serves as a unified entry point. It must detect the target API version and route authentication requests to the appropriate provider (Azure AD for v3 or Keycloak for v5). + +**3. Keycloak User & Group Management** + +The Admin Portal integrates directly with **Keycloak** to manage access control. + +* **User Management:** Administrators must be able to list, view, and manage users stored in Keycloak. +* **Group Mapping:** The portal will manage Keycloak Groups, which correspond to platform roles (Admin, Editor, Viewer). +* **Organization Isolation:** Users and groups must be filtered based on the selected Organization to ensure strict multi-tenant security. + +## **4. Admin Portal: First Page Requirements** + +The landing page of the Admin Portal provides a "high-level" overview of the platform's health and hierarchy. + +### **4.1 Organizations Dashboard** + +The entry point displays all accessible **Organizations**. + +* **Search/Filter:** Ability to filter organizations by API version (v3 vs v5). +* **Organization Details:** Quick view of the number of active Workspaces and Solutions within each organization. + +### **4.2 Keycloak User Integration** + +A dedicated section for **Identity Management**: + +* Display a list of users fetched from the Keycloak Realm. +* Ability to assign/remove users from platform-specific groups. + +### **4.3 Platform Flowchart (Hierarchy View)** + +The portal features a dynamic flowchart that visualizes the platform's object hierarchy. This chart **automatically adapts its structure** depending on whether the user is viewing an **API v3** or **API v5** environment. #**TO CONTINUE** + + +# 5. Organization Drill-Down (API v5 Focus) + +This section details the navigation flow once a specific organization is selected. These functionalities and object structures are specifically designed for the **API v5** architecture. + +## 5.1 Organization Dashboard +Upon selecting an organization from the main page, the administrator is redirected to the Organization management view. + +* **Navigation Bar:** A dedicated sidebar appears, providing direct access to **Solutions** and **Workspaces** belonging to the selected organization. +* **Contextual Filtering:** All data displayed in the following modules is strictly filtered by the active Organization ID to ensure multi-tenant isolation and security. + +--- + +## 5.2 Module "Solutions" +Management of simulation definitions and logic attached to the organization. + +### 5.2.1 Solutions Table View +A comprehensive list of available solutions within the organization. +* **Columns:** * **Name:** Name of the solution. **#TODO** + * **ID:** Unique technical identifier. + * **Version:** Version number of the solution. + * **Type:** Simulator engine type. + * **Creation Date:** Timestamp of when the solution was added. +* **Actions:** Add (Upload JSON/YAML), Update, and Delete.**#TODO** + +### 5.2.2 Solution Detail View +Triggered by clicking on a specific solution row. +* **#TODO: Overview:** (Reserved section for technical metadata and general description). +* **Run Templates:** A list of execution templates declared within the solution file, defining how simulations can be run. + +--- + +## 5.3 Module "Workspaces" +The Workspace is the contextual analysis space linked to a specific solution. It is the primary area for operational tasks. + +### 5.3.1 Workspaces Table View +A central hub for managing all workspaces within the organization. +* **Columns:** **#TODO** + * **Name:** Display name of the workspace. + * **ID:** Unique technical identifier. + * **Solution:** Associated solution name (clickable link for quick navigation). + * **Description:** Brief summary of the business use case. + * **Access Control:** Summary of assigned roles and permissions (ACL). +* **CRUD Management:** Dedicated interface buttons to **Add** a new workspace, **Update** existing configurations, or **Archive/Delete**. + +### 5.3.2 Workspace Detail View +Opening a workspace provides access to its specific operational components: + +#### **A. Runners** +* **Runners Table:** Displays all runners created within this workspace. +* **Management:** Capability to create new runners, configure security access per runner, and monitor execution statuses. + +#### **B. Datasets** +* **Datasets Table:** Lists all data sources linked to the workspace. + * **Supported Types:** Local files, Databases, Azure Digital Twins (ADT) links, etc. +* **Data Management:** * **Association:** Ability to link/associate a specific dataset to a Runner for execution. + * **Updates:** Modify the data source parameters (e.g., changing a connection string or uploading a new file version). + + diff --git a/docs/functional/00 2 User Personas.md b/docs/requirements/00 core requirements/02-User Personas.md similarity index 100% rename from docs/functional/00 2 User Personas.md rename to docs/requirements/00 core requirements/02-User Personas.md diff --git a/docs/requirements/00 core requirements/03-admin-portal-main.md b/docs/requirements/00 core requirements/03-admin-portal-main.md new file mode 100644 index 0000000..8f046e0 --- /dev/null +++ b/docs/requirements/00 core requirements/03-admin-portal-main.md @@ -0,0 +1,32 @@ + + + +# Admin Portal Main View Requirements + +The Admin Portal provides a centralized interface for platform management. + +## 1. Global Navigation Bar + +The main navigation bar provides direct access to the following core modules: +* **Organizations** (Default View) +* **Flowchart** +* **Users** + +## 2. Organizations Dashboard + +The entry point (and default view) displays all accessible **Organizations**. + +* **Search/Filter:** Ability to filter organizations by API version (v3 vs v5). +* **Organization Details:** Quick view of the number of active Workspaces and Solutions within each organization. +* **Navigation:** Clicking on an organization card/row navigates to the [Organization View](./03-organization-view.md). + +## 3. Users Management + +A dedicated section for **Identity Management**, accessible via the "Users" navigation item: + +* Display a list of users fetched from the Keycloak Realm. +* Ability to assign/remove users from platform-specific groups. + +## 4. Platform Flowchart (Hierarchy View) + +Accessible via the "Flowchart" navigation item, this dynamic chart visualizes the platform's object hierarchy. This chart **automatically adapts its structure** depending on whether the user is viewing an **API v3** or **API v5** environment. \ No newline at end of file diff --git a/docs/requirements/00 core requirements/03-overview.md b/docs/requirements/00 core requirements/03-overview.md new file mode 100644 index 0000000..a3b96f5 --- /dev/null +++ b/docs/requirements/00 core requirements/03-overview.md @@ -0,0 +1,115 @@ + + +# **Cosmo Tech Platform Portal: Requirements** + +## **1. Introduction** + +The Cosmo Tech **Platform Portal** is a centralized suite of services for platform administrators. It is designed to oversee multiple organizations, manage global configurations, and ensure compliance. + +The primary module is the **Admin Portal**, a web-based interface that provides an intuitive environment for managing the lifecycle of Cosmo Tech platform objects. + +## **2. Platform Architecture & Multi-API Support** + +The Admin Portal must act as a bridge between two distinct generations of the Cosmo Tech API, handling the transition between cloud-native and on-premise environments. + +### **2.1 API Versions** + +| **Feature** | **API v3** | **API v5** | +| :---: | :---: | :---: | +| **Deployment** | Azure (Cloud) | On-Premise / Self-Hosted | +| **Auth Provider** | Azure Active Directory (Microsoft Entra ID) | **Keycloak** | +| **Primary Objects** | Organizations, Solutions, Workspaces, Scenarios… | Organizations, Solutions, Workspaces, Runners, Runs | + +### **2.2 Unified Authentication Flow** + +The Admin Portal serves as a unified entry point. It must detect the target API version and route authentication requests to the appropriate provider (Azure AD for v3 or Keycloak for v5). + +**3. Keycloak User & Group Management** + +The Admin Portal integrates directly with **Keycloak** to manage access control. + +* **User Management:** Administrators must be able to list, view, and manage users stored in Keycloak. +* **Group Mapping:** The portal will manage Keycloak Groups, which correspond to platform roles (Admin, Editor, Viewer). +* **Organization Isolation:** Users and groups must be filtered based on the selected Organization to ensure strict multi-tenant security. + +## **4. Admin Portal: First Page Requirements** + +The landing page of the Admin Portal provides a "high-level" overview of the platform's health and hierarchy. + +### **4.1 Organizations Dashboard** + +The entry point displays all accessible **Organizations**. + +* **Search/Filter:** Ability to filter organizations by API version (v3 vs v5). +* **Organization Details:** Quick view of the number of active Workspaces and Solutions within each organization. + +### **4.2 Keycloak User Integration** + +A dedicated section for **Identity Management**: + +* Display a list of users fetched from the Keycloak Realm. +* Ability to assign/remove users from platform-specific groups. + +### **4.3 Platform Flowchart (Hierarchy View)** + +The portal features a dynamic flowchart that visualizes the platform's object hierarchy. This chart **automatically adapts its structure** depending on whether the user is viewing an **API v3** or **API v5** environment. #**TO CONTINUE** + + +# 5. Organization Drill-Down (API v5 Focus) + +This section details the navigation flow once a specific organization is selected. These functionalities and object structures are specifically designed for the **API v5** architecture. + +## 5.1 Organization Dashboard +Upon selecting an organization from the main page, the administrator is redirected to the Organization management view. + +* **Navigation Bar:** A dedicated sidebar appears, providing direct access to **Solutions** and **Workspaces** belonging to the selected organization. +* **Contextual Filtering:** All data displayed in the following modules is strictly filtered by the active Organization ID to ensure multi-tenant isolation and security. + +--- + +## 5.2 Module "Solutions" +Management of simulation definitions and logic attached to the organization. + +### 5.2.1 Solutions Table View +A comprehensive list of available solutions within the organization. +* **Columns:** * **Name:** Name of the solution. **#TODO** + * **ID:** Unique technical identifier. + * **Version:** Version number of the solution. + * **Type:** Simulator engine type. + * **Creation Date:** Timestamp of when the solution was added. +* **Actions:** Add (Upload JSON/YAML), Update, and Delete.**#TODO** + +### 5.2.2 Solution Detail View +Triggered by clicking on a specific solution row. +* **#TODO: Overview:** (Reserved section for technical metadata and general description). +* **Run Templates:** A list of execution templates declared within the solution file, defining how simulations can be run. + +--- + +## 5.3 Module "Workspaces" +The Workspace is the contextual analysis space linked to a specific solution. It is the primary area for operational tasks. + +### 5.3.1 Workspaces Table View +A central hub for managing all workspaces within the organization. +* **Columns:** **#TODO** + * **Name:** Display name of the workspace. + * **ID:** Unique technical identifier. + * **Solution:** Associated solution name (clickable link for quick navigation). + * **Description:** Brief summary of the business use case. + * **Access Control:** Summary of assigned roles and permissions (ACL). +* **CRUD Management:** Dedicated interface buttons to **Add** a new workspace, **Update** existing configurations, or **Archive/Delete**. + +### 5.3.2 Workspace Detail View +Opening a workspace provides access to its specific operational components: + +#### **A. Runners** +* **Runners Table:** Displays all runners created within this workspace. +* **Management:** Capability to create new runners, configure security access per runner, and monitor execution statuses. + +#### **B. Datasets** +* **Datasets Table:** Lists all data sources linked to the workspace. + * **Supported Types:** Local files, Databases, Azure Digital Twins (ADT) links, etc. +* **Data Management:** * **Association:** Ability to link/associate a specific dataset to a Runner for execution. + * **Updates:** Modify the data source parameters (e.g., changing a connection string or uploading a new file version). + + diff --git a/docs/requirements/00-login.md b/docs/requirements/00-login.md new file mode 100644 index 0000000..1f2f30d --- /dev/null +++ b/docs/requirements/00-login.md @@ -0,0 +1,3 @@ + + +The login page page presents. A drop down list. With all the different tenants that the user has access to. After selecting a value from the list. The user is redirected to the home page of this tenant. Technical details. When recovering the tenant, we determine the type of the API if its API V 3 or API V5. And we also. Make a request to the API to get the list of organizations in the tenant. Most of the time there will be only one organization. Then the user is redirected to the detailed view of the first organization in this tenant. \ No newline at end of file diff --git a/docs/requirements/01-homepage.md b/docs/requirements/01-homepage.md new file mode 100644 index 0000000..116aacb --- /dev/null +++ b/docs/requirements/01-homepage.md @@ -0,0 +1,20 @@ + + + +The home page of the portal admin is the organization view page of the main organization of the current tenant. + +Most of the cases there is only one organization, so the user will land on the default organization after login. + +This page has the standard navigation format (menus on the left, main body in the middle) + +Menus: + +Solutions => a click on this menu displays the Solutions List View showing the solutions of this organization + +Workspaces => a click on this menu displays the Workspaces List View showing the workspaces of this organization + +Users & Roles + +Flowchart + +main content : diff --git a/docs/requirements/02-workspacesview.md b/docs/requirements/02-workspacesview.md new file mode 100644 index 0000000..0c677f8 --- /dev/null +++ b/docs/requirements/02-workspacesview.md @@ -0,0 +1,22 @@ + + + +# Workspaces View Requirements + +## 1. Module "Workspaces" +After choosing an organization, the user sees a list of its workspaces. + +### 1.1 Page Header +* **Top Left**: An **Organization Selector** to view or switch the current organization. +* **Top Right**: An **"Add Workspace"** button to initiate creation. + +### 1.2 Workspaces List Table +* **ID**: Unique technical ID. +* **Name**: Display name. +* **Actions**: Buttons for **Manage** and **Delete**. + +### 1.3 Key Features +* **Add Workspace**: Clicking the button opens a **pop-up (Add Workspace modal)**. +* **Manage Action**: Clicking "Manage" opens a **pop-up (Manage modal)** to edit settings (detailed in Manage View). +* **Row Navigation**: Clicking a row takes the user to a new page: the **Workspace Detail View**. +* **Access Control**: Buttons are only visible if the user has the required permissions. \ No newline at end of file diff --git a/docs/requirements/04-organization-view.md b/docs/requirements/04-organization-view.md new file mode 100644 index 0000000..bf7477c --- /dev/null +++ b/docs/requirements/04-organization-view.md @@ -0,0 +1,49 @@ + + +# Organization View Requirements (API v5 Focus) + +This document details the navigation flow and requirements once a specific organization is selected. These functionalities and object structures are specifically designed for the **API v5** architecture. + +## 1. Organization Dashboard +Upon selecting an organization from the main page, the administrator is redirected to the Organization management view. + +* **Navigation Bar:** A dedicated sidebar appears, providing direct access to **Solutions** and **Workspaces** belonging to the selected organization. +* **Contextual Filtering:** All data displayed in the following modules is strictly filtered by the active Organization ID to ensure multi-tenant isolation and security. + +--- + +## 2. Solutions Management + +This section describes the "Solutions" tab or module within the Organization View. + +### 2.1 Solutions Table +The view presents a list of all solutions available in the organization. + +**Columns:** +* **Name:** Name of the solution. +* **ID:** Unique technical identifier. +* **Version:** Version number of the solution. +* **Type:** Simulator engine type. +* **Creation Date:** Timestamp of when the solution was added. + +### 2.2 Navigation +* **Interaction:** Clicking on a row in the Solutions table will navigate the user to the **[Solution View](./04-solutions-view.md)**, where they can manage run templates and other details. + +--- + +## 3. Workspaces Management + +This section describes the "Workspaces" tab or module within the Organization View. + +### 3.1 Workspaces Table +The view presents a list of all operational workspaces within the organization. + +**Columns:** +* **Name:** Display name of the workspace. +* **ID:** Unique technical identifier. +* **Solution:** Associated solution name. +* **Description:** Brief summary of the business use case. +* **Access Control:** Summary of assigned roles and permissions (ACL). + +### 3.2 Navigation +* **Interaction:** Clicking on a row in the Workspaces table will navigate the user to the **[Workspace View](./05-workspaces-view.md)**, where they can manage runners and datasets. diff --git a/docs/requirements/04-solutions-view.md b/docs/requirements/04-solutions-view.md new file mode 100644 index 0000000..6ce7ba0 --- /dev/null +++ b/docs/requirements/04-solutions-view.md @@ -0,0 +1,23 @@ + + +# Solutions View Requirements + +## 1. Module "Solutions" +Management of simulation definitions and logic attached to the organization. + +### 1.1 Solutions Table View +A comprehensive list of available solutions within the organization. + +* **Columns:** + * **Name:** Name of the solution. **#TODO: Verify complete list of columns** + * **ID:** Unique technical identifier. + * **Version:** Version number of the solution. + * **Type:** Simulator engine type. + * **Creation Date:** Timestamp of when the solution was added. +* **Actions:** Add (Upload JSON/YAML), Update, and Delete.**#TODO: Detail specific actions behavior** + +### 1.2 Solution Detail View +Triggered by clicking on a specific solution row. + +* **Overview:** (Reserved section for technical metadata and general description). **#TODO: Define specific metadata fields** +* **Run Templates:** A list of execution templates declared within the solution file, defining how simulations can be run. diff --git a/docs/requirements/05-workspaces-view.md b/docs/requirements/05-workspaces-view.md new file mode 100644 index 0000000..9091924 --- /dev/null +++ b/docs/requirements/05-workspaces-view.md @@ -0,0 +1,31 @@ + + +# Workspaces View Requirements + +## 1. Module "Workspaces" +The Workspace is the contextual analysis space linked to a specific solution. It is the primary area for operational tasks. + +### 1.1 Workspaces Table View +A central hub for managing all workspaces within the organization. + +* **Columns:** **#TODO: Verify column list** + * **Name:** Display name of the workspace. + * **ID:** Unique technical identifier. + * **Solution:** Associated solution name (clickable link for quick navigation). + * **Description:** Brief summary of the business use case. + * **Access Control:** Summary of assigned roles and permissions (ACL). +* **CRUD Management:** Dedicated interface buttons to **Add** a new workspace, **Update** existing configurations, or **Archive/Delete**. + +### 1.2 Workspace Detail View +Opening a workspace provides access to its specific operational components: + +#### A. Runners +* **Runners Table:** Displays all runners created within this workspace. +* **Management:** Capability to create new runners, configure security access per runner, and monitor execution statuses. + +#### B. Datasets +* **Datasets Table:** Lists all data sources linked to the workspace. + * **Supported Types:** Local files, Databases, Azure Digital Twins (ADT) links, etc. +* **Data Management:** + * **Association:** Ability to link/associate a specific dataset to a Runner for execution. + * **Updates:** Modify the data source parameters (e.g., changing a connection string or uploading a new file version). diff --git a/docs/architecture/Project_Architecture_Blueprint.md b/docs/technical-design/00-architecture/Project_Architecture_Blueprint.md similarity index 100% rename from docs/architecture/Project_Architecture_Blueprint.md rename to docs/technical-design/00-architecture/Project_Architecture_Blueprint.md diff --git a/docs/technical-design/00-architecture/V5/5-onprem-endpoints.md b/docs/technical-design/00-architecture/V5/5-onprem-endpoints.md new file mode 100644 index 0000000..8a452fe --- /dev/null +++ b/docs/technical-design/00-architecture/V5/5-onprem-endpoints.md @@ -0,0 +1,174 @@ + + + +# API v5 Technical Specifications (On-Prem / Keycloak) + +This document defines the models and endpoints used by the Admin Portal to manage the platform. It is based on the `@cosmotech/api-ts@5.0.0-rc5` library. + +**CRITICAL REFERENCE:** This document provides a high-level mapping for development. For exhaustive technical details, including full schemas, field constraints, and example payloads, refer to the source OpenAPI file: + +📄 `docs_orgn/api-specs/V5/openapi-5.0.0-rc5.json` + +## 1. Base API Information + +- **Version:** 5.0.1-SNAPSHOT +- **Auth Provider:** Keycloak (Bearer Token via OAuth2) +- **Client Library:** `@cosmotech/api-ts` + +## 2. Core Data Models (Schemas) + +### 2.1 Organization + +The root object for multi-tenancy. + +```typescript +interface Organization { + id: string; // Pattern: ^o-\w{10,20} + name: string; + security: { + default: string; // e.g., 'none', 'viewer', 'user', 'editor', 'admin' + accessControlList: Array<{ id: string; role: string }>; + }; +} +``` + +### 2.2 Solution + +The simulation engine definition. + +```typescript +export interface Solution { + id: string; // Pattern: ^sol-\w{10,20} + key: string; + name: string; + description?: string; + version: string; + repository: string; + runTemplates: Array<{ + id: string; + name: string; + description?: string; + // Other properties like tags, computeSize, parameterGroups + }>; +} +``` + +### 2.3 Workspace + +The business context linking a Solution to specific datasets. + +```typescript +export interface Workspace { + id: string; // Pattern: ^w-\w{10,20} + key: string; + name: string; + description?: string; + organizationId: string; + solution: { + solutionId: string; // Linked Solution ID + datasetId?: string; // Optional linked Dataset ID + defaultParameterValues?: Record; + }; +} +``` + +### 2.4 Runner (v5 Specific) + +An execution entity for running simulations or ETLs. + +```typescript +export interface Runner { + id: string; // Pattern: ^(r|s)-\w{10,20} + name: string; + description?: string; + organizationId: string; + workspaceId: string; + solutionId: string; + runTemplateId: string; + validationStatus: 'Draft' | 'Rejected' | 'Unknown' | 'Validated'; +} +``` + +## 3. Key API Endpoints Mapping + +The Admin Portal uses the following routes from the OrganizationApi, WorkspaceApi, and RunnerApi classes. + +**Note:** Path parameters follow the `snake_case` naming convention from the OpenAPI spec. + +### 3.1. Organizations (Multi-tenancy) + +| Méthode | Endpoint | Description | +|:--------|:---------|:------------| +| `GET` | `/organizations` | Lister toutes les organisations (pagination via page, size) | +| `GET` | `/organizations/{organization_id}` | Récupérer les détails d'une organisation | +| `POST` | `/organizations` | Créer une nouvelle organisation | +| `PATCH` | `/organizations/{organization_id}` | Modifier une organisation (nom) | +| `DELETE` | `/organizations/{organization_id}` | Supprimer une organisation | +| `GET` | `/organizations/{organization_id}/security` | Lister la sécurité (ACL) de l'organisation | +| `POST` | `/organizations/{organization_id}/security/access` | Ajouter un contrôle d'accès à l'organisation | + +### 3.2. Solutions (Logic & Simulation) + +| Méthode | Endpoint | Description | +|:--------|:---------|:------------| +| `GET` | `/organizations/{organization_id}/solutions` | Lister toutes les solutions | +| `GET` | `/organizations/{organization_id}/solutions/{solution_id}` | Détails d'une solution spécifique | +| `POST` | `/organizations/{organization_id}/solutions` | Créer une solution | +| `PATCH` | `/organizations/{organization_id}/solutions/{solution_id}` | Mettre à jour une solution | +| `DELETE` | `/organizations/{organization_id}/solutions/{solution_id}` | Supprimer une solution | + +### 3.3. Workspaces (Operational Context) + +| Méthode | Endpoint | Description | +|:--------|:---------|:------------| +| `GET` | `/organizations/{organization_id}/workspaces` | Lister les workspaces d'une organisation | +| `GET` | `/organizations/{organization_id}/workspaces/{workspace_id}` | Détails d'un workspace | +| `POST` | `/organizations/{organization_id}/workspaces` | Créer un workspace | +| `PATCH` | `/organizations/{organization_id}/workspaces/{workspace_id}` | Modifier un workspace | +| `DELETE` | `/organizations/{organization_id}/workspaces/{workspace_id}` | Supprimer un workspace | +| `GET` | `/organizations/{organization_id}/workspaces/{workspace_id}/security` | Consulter la sécurité du workspace | + +### 3.4. Runners (v5 Execution Engine) + +| Méthode | Endpoint | Description | +|:--------|:---------|:------------| +| `GET` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners` | Lister les runners d'un workspace | +| `GET` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}` | Détails d'un runner | +| `POST` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners` | Créer un nouveau runner | +| `PATCH` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}` | Modifier un runner | +| `DELETE` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}` | Supprimer un runner | +| `POST` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/start` | Lancer une exécution (Run) | +| `POST` | `/organizations/{organization_id}/workspaces/{workspace_id}/runners/{runner_id}/stop` | Arrêter la dernière exécution | + +### 3.5. Datasets & Connectors + +| Méthode | Endpoint | Description | +|:--------|:---------|:------------| +| `GET` | `/organizations/{organization_id}/workspaces/{workspace_id}/datasets` | Lister les datasets liés au workspace | +| `POST` | `/organizations/{organization_id}/workspaces/{workspace_id}/datasets` | Créer un nouveau dataset | +| `DELETE` | `/organizations/{organization_id}/workspaces/{workspace_id}/datasets/{dataset_id}` | Supprimer un dataset | +| `GET` | `/organizations/{organization_id}/connectors` | Lister les connecteurs disponibles | + +--- + +## 4. Integration Guidelines for Copilot + +- **Hierarchy Awareness:** Every API call for Workspaces, Solutions, or Runners must include the `organization_id` in the path as defined in the spec. +- **Keycloak Integration:** + - Tokens are passed in the `Authorization: Bearer ` header. + - User identities in the `security.accessControlList` refer to Keycloak `id` (often an email or sub). +- **Pagination:** For lists (Organizations, Workspaces, Runners), use the `page` and `size` query parameters. +- **State Management:** When a Runner's last run is `Running`, the portal should poll the `/status` endpoint of the Run to update the UI. + + + +## old file + + + +The data (organizations, solutions, workspaces) is provided by the Cosmo Tech API. We will use the v5 of the API. + +The portal admin uses the official TypeScript client library: [@cosmotech/api-ts] +https://www.npmjs.com/package/@cosmotech/api-ts/v/5.0.0-rc5 . + +The diff --git a/docs/architecture/V5/openapi-5.0.0-rc5.json b/docs/technical-design/00-architecture/V5/openapi-5.0.0-rc5.json similarity index 100% rename from docs/architecture/V5/openapi-5.0.0-rc5.json rename to docs/technical-design/00-architecture/V5/openapi-5.0.0-rc5.json diff --git a/docs/technical-design/00-architecture/api-bridge-strategy.md b/docs/technical-design/00-architecture/api-bridge-strategy.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/technical-design/00-architecture/auth-flow-keycloak.md b/docs/technical-design/00-architecture/auth-flow-keycloak.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/technical-design/00-login-design.md b/docs/technical-design/00-login-design.md new file mode 100644 index 0000000..11713c8 --- /dev/null +++ b/docs/technical-design/00-login-design.md @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/package.json b/package.json index 3e4b4b4..c95639c 100644 --- a/package.json +++ b/package.json @@ -50,6 +50,7 @@ "globals": "^15.14.0", "neostandard": "^0.12.1", "prettier": "3.5.0", + "typescript": "^5.9.3", "vite": "^6.1.0", "vite-plugin-node-polyfills": "^0.23.0" }, diff --git a/src/AppWrapper.jsx b/src/AppWrapper.jsx index a92b04f..dc73a05 100644 --- a/src/AppWrapper.jsx +++ b/src/AppWrapper.jsx @@ -5,6 +5,7 @@ import { useSelector } from 'react-redux'; import { CssBaseline } from '@mui/material'; import { ThemeProvider } from '@mui/material/styles'; import App from './App.jsx'; +import DataLoader from './components/DataLoader/DataLoader.jsx'; import { createAppTheme } from './themes'; export const AppWrapper = () => { @@ -14,6 +15,7 @@ export const AppWrapper = () => { return ( + ); diff --git a/src/components/DataLoader/DataLoader.jsx b/src/components/DataLoader/DataLoader.jsx new file mode 100644 index 0000000..284701d --- /dev/null +++ b/src/components/DataLoader/DataLoader.jsx @@ -0,0 +1,25 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +import { useEffect } from 'react'; +import { useFetchInitialData } from '../../state/app/hooks.js'; +import { AUTH_STATUS } from '../../state/auth/constants.js'; +import { useAuth } from '../../state/auth/hooks.js'; + +/** + * DataLoader component watches for authentication status changes + * and triggers initial data fetching when user becomes authenticated. + */ +export default function DataLoader() { + const { status } = useAuth(); + const fetchInitialData = useFetchInitialData(); + + useEffect(() => { + if (status === AUTH_STATUS.AUTHENTICATED) { + console.log('[DataLoader] Auth status changed to AUTHENTICATED, fetching initial data...'); + fetchInitialData(); + } + }, [status, fetchInitialData]); + + // This component doesn't render anything + return null; +} diff --git a/src/state/app/constants.js b/src/state/app/constants.js new file mode 100644 index 0000000..3c2ed25 --- /dev/null +++ b/src/state/app/constants.js @@ -0,0 +1,10 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech + +// Application loading statuses +export const APP_STATUS = { + IDLE: 'IDLE', + LOADING: 'LOADING', + SUCCESS: 'SUCCESS', + ERROR: 'ERROR', +}; diff --git a/src/state/app/hooks.js b/src/state/app/hooks.js new file mode 100644 index 0000000..285f70e --- /dev/null +++ b/src/state/app/hooks.js @@ -0,0 +1,16 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +import { useCallback } from 'react'; +import { useDispatch, useSelector } from 'react-redux'; +import fetchInitialData from './thunks/fetchInitialData.js'; + +// Selectors +export const useAppStatus = () => useSelector((state) => state.app.status); +export const useAppError = () => useSelector((state) => state.app.error); +export const useApiVersion = () => useSelector((state) => state.app.apiVersion); + +// Action dispatchers +export const useFetchInitialData = () => { + const dispatch = useDispatch(); + return useCallback(() => dispatch(fetchInitialData()), [dispatch]); +}; diff --git a/src/state/app/index.js b/src/state/app/index.js new file mode 100644 index 0000000..1c6bd2c --- /dev/null +++ b/src/state/app/index.js @@ -0,0 +1,6 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +export { default as appReducer } from './reducers.js'; +export * from './constants.js'; +export * from './hooks.js'; +export * from './thunks/index.js'; diff --git a/src/state/app/reducers.js b/src/state/app/reducers.js new file mode 100644 index 0000000..552468f --- /dev/null +++ b/src/state/app/reducers.js @@ -0,0 +1,30 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +import { createSlice } from '@reduxjs/toolkit'; +import { APP_STATUS } from './constants.js'; + +const initialState = { + status: APP_STATUS.IDLE, + error: null, + apiVersion: null, +}; + +const appSlice = createSlice({ + name: 'app', + initialState, + reducers: { + setAppStatus: (state, action) => { + state.status = action.payload.status; + if (action.payload.error !== undefined) { + state.error = action.payload.error; + } + }, + setApiVersion: (state, action) => { + state.apiVersion = action.payload.apiVersion; + }, + resetAppState: () => initialState, + }, +}); + +export const { setAppStatus, setApiVersion, resetAppState } = appSlice.actions; +export default appSlice.reducer; diff --git a/src/state/app/thunks/fetchInitialData.js b/src/state/app/thunks/fetchInitialData.js new file mode 100644 index 0000000..87c4b7c --- /dev/null +++ b/src/state/app/thunks/fetchInitialData.js @@ -0,0 +1,57 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +import { APP_STATUS } from '../constants.js'; +import { setAppStatus } from '../reducers.js'; + +/** + * Thunk to fetch all initial data after authentication. + * Fetches organizations, workspaces, permissions and logs the results. + */ +function fetchInitialData() { + return async (dispatch, getState, extraArgument) => { + const { api } = extraArgument; + + dispatch(setAppStatus({ status: APP_STATUS.LOADING })); + + try { + // Fetch organizations + console.log('[FetchInitialData] Fetching organizations...'); + const { data: organizations } = await api.Organizations.findAllOrganizations(); + console.log('[FetchInitialData] Organizations fetched:', organizations); + + // Fetch workspaces for each organization + console.log('[FetchInitialData] Fetching workspaces...'); + const workspacesResults = []; + for (const org of organizations) { + try { + const { data: workspaces } = await api.Workspaces.findAllWorkspaces(org.id); + workspacesResults.push({ organizationId: org.id, workspaces }); + } catch (error) { + console.warn(`[FetchInitialData] Could not fetch workspaces for org ${org.id}:`, error.message); + } + } + console.log('[FetchInitialData] Workspaces fetched:', workspacesResults); + + // Log summary + console.log('[FetchInitialData] ===== INITIAL DATA SUMMARY ====='); + console.log('[FetchInitialData] Total organizations:', organizations.length); + console.log( + '[FetchInitialData] Total workspaces:', + workspacesResults.reduce((acc, r) => acc + r.workspaces.length, 0) + ); + console.log('[FetchInitialData] ================================'); + + dispatch(setAppStatus({ status: APP_STATUS.SUCCESS })); + } catch (error) { + console.error('[FetchInitialData] Error fetching initial data:', error); + dispatch( + setAppStatus({ + status: APP_STATUS.ERROR, + error: error.message || 'Failed to fetch initial data', + }) + ); + } + }; +} + +export default fetchInitialData; diff --git a/src/state/app/thunks/index.js b/src/state/app/thunks/index.js new file mode 100644 index 0000000..d38be84 --- /dev/null +++ b/src/state/app/thunks/index.js @@ -0,0 +1,3 @@ +// SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech +// SPDX-License-Identifier: LicenseRef-CosmoTech +export { default as fetchInitialData } from './fetchInitialData.js'; diff --git a/src/state/rootReducer.js b/src/state/rootReducer.js index d769c83..6203f44 100644 --- a/src/state/rootReducer.js +++ b/src/state/rootReducer.js @@ -2,12 +2,14 @@ // SPDX-License-Identifier: LicenseRef-CosmoTech import { combineReducers } from '@reduxjs/toolkit'; import { cosmoApi } from './api/apiSlice.js'; +import appReducer from './app/reducers.js'; import authReducer from './auth/reducers.js'; import organizationsReducer from './organizations/reducers.js'; import themeReducer from './theme/reducers.js'; import workspacesReducer from './workspaces/reducers.js'; const rootReducer = combineReducers({ + app: appReducer, auth: authReducer, theme: themeReducer, organizations: organizationsReducer, diff --git a/src/themes/index.js b/src/themes/index.js index a6ba9c6..8cec7e8 100644 --- a/src/themes/index.js +++ b/src/themes/index.js @@ -49,7 +49,7 @@ const getThemeConfig = (mode = 'light') => ({ styleOverrides: { root: { '&:hover': { - backgroundColor: mode === 'light' ? '#f8f9fa' : '#252525 !important', + backgroundColor: mode === 'light' ? '#f8f9fa' : '#252525', }, }, }, diff --git a/yarn.lock b/yarn.lock index b0bf3b5..308388a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -289,6 +289,7 @@ __metadata: react-i18next: "npm:^16.5.4" react-redux: "npm:^9.2.0" react-router: "npm:^7.1.5" + typescript: "npm:^5.9.3" vite: "npm:^6.1.0" vite-plugin-node-polyfills: "npm:^0.23.0" languageName: unknown @@ -6045,6 +6046,26 @@ __metadata: languageName: node linkType: hard +"typescript@npm:^5.9.3": + version: 5.9.3 + resolution: "typescript@npm:5.9.3" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: 10c0/6bd7552ce39f97e711db5aa048f6f9995b53f1c52f7d8667c1abdc1700c68a76a308f579cd309ce6b53646deb4e9a1be7c813a93baaf0a28ccd536a30270e1c5 + languageName: node + linkType: hard + +"typescript@patch:typescript@npm%3A^5.9.3#optional!builtin": + version: 5.9.3 + resolution: "typescript@patch:typescript@npm%3A5.9.3#optional!builtin::version=5.9.3&hash=5786d5" + bin: + tsc: bin/tsc + tsserver: bin/tsserver + checksum: 10c0/ad09fdf7a756814dce65bc60c1657b40d44451346858eea230e10f2e95a289d9183b6e32e5c11e95acc0ccc214b4f36289dcad4bf1886b0adb84d711d336a430 + languageName: node + linkType: hard + "unbox-primitive@npm:^1.1.0": version: 1.1.0 resolution: "unbox-primitive@npm:1.1.0"