add docs folder

.github/instructions/copilot-instructions.md → .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)

docs/plan/00-login-plan.md

@@ -0,0 +1,58 @@
+<!-- SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech -->
+<!-- SPDX-License-Identifier: LicenseRef-CosmoTech -->
+# 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.

docs/requirements/00 core requirements/01-Platform Portal Requirements.md

@@ -0,0 +1,115 @@
+<!-- SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech -->
+<!-- SPDX-License-Identifier: LicenseRef-CosmoTech -->
+# **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).
+
+

docs/requirements/00 core requirements/03-admin-portal-main.md

@@ -0,0 +1,32 @@
+<!-- SPDX-FileCopyrightText: Copyright (C) 2024-2025 Cosmo Tech -->
+<!-- SPDX-License-Identifier: LicenseRef-CosmoTech -->
+
+# 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.