feat(KFLUXUI-592): improve the Readme.md for system notifications

Author: testcara

.github/workflows/validate-notification.yaml

@@ -0,0 +1,63 @@
+name: Validate System Notification ConfigMaps
+
+on:
+  pull_request:
+    paths:
+      - "components/konflux-info/system-notifications/**/*.yaml"
+      - "components/konflux-info/notification-schema.json"
+env:
+  NOTIFICATION_DIR: components/konflux-info
+  SCHEMA_FILE: components/konflux-info/notification-schema.json
+  TMP_DIR: .tmp/notifications
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install yq (YAML processor)
+        run: |
+          sudo wget https://github.com/mikefarah/yq/releases/download/v4.34.1/yq_linux_amd64 -O /usr/bin/yq
+          sudo chmod +x /usr/bin/yq
+
+      - name: Check konflux-system-notification label present
+        run: |
+          mkdir -p ${{ env.TMP_DIR }}
+          for file in  ${{ env.NOTIFICATION_DIR }}/**/**/system-notifications/*.yaml; do
+            if [[ "$(basename "$file")" == "kustomization.yaml" ]]; then
+              continue
+            fi
+            label=$(yq e '.metadata.labels."konflux.system.notification"' "$file")
+            if [[ "$label" != "\"true\"" && "$label" != "true" ]]; then
+              echo "ERROR: $file is missing konflux-system-notification: \"true\" label"
+              exit 1
+            fi
+          done
+
+      - name: Validate notification-content.json against schema
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+
+      - name: Install ajv-cli for JSON Schema validation
+        run: |
+          npm install -g ajv-cli
+
+      - name: Validate notification-content.json files
+        run: |
+          mkdir -p ${{ env.TMP_DIR }}
+          for file in  ${{ env.NOTIFICATION_DIR }}/**/**/system-notifications/*.yaml; do
+            file_name=$(basename "$file")
+            if [[ "$file_name" == "kustomization.yaml" ]]; then
+              continue
+            fi
+            # Extract JSON content from ConfigMap
+            yq e '.data."notification-content.json"' "$file" > "${TMP_DIR}/${file_name}.json"
+            ajv validate -s "${SCHEMA_FILE}" -d "${TMP_DIR}/${file_name}.json" --errors=text
+            if [ $? -ne 0 ]; then
+              echo "ERROR: notification-content.json in ${file} does not validate against schema"
+              exit 1
+            fi
+          done

components/konflux-info/README.md

@@ -1,33 +1,60 @@
+_Follow links by Ctrl + click (or Cmd + click on Mac)_
+
+- 1. [📂 Directory Structure](#DirectoryStructure)
+- 2. [📢 Konflux Banner](#KonfluxBanner)
+  - 2.1. [✅ Banner Content Validation](#BannerContentValidation)
+  - 2.2. [✅ Banner Content Specification](#BannerContentSpecification)
+    - 2.2.1. [**Schema**](#Schema)
+    - 2.2.2. [**Required and Optional Fields for Each Banner**](#RequiredandOptionalFieldsforEachBanner)
+  - 2.3. [Usage Scenarios & Examples](#UsageScenariosExamples)
+    - 2.3.1. [✅ **1. Multiple Banners**](#1.MultipleBanners)
+    - 2.3.2. [✅ **2. One-Time Banner**](#2.One-TimeBanner)
+    - 2.3.3. [✅ **3. Weekly Recurring Banner**](#3.WeeklyRecurringBanner)
+    - 2.3.4. [✅ **4. Monthly Recurring Banner**](#4.MonthlyRecurringBanner)
+    - 2.3.5. [✅ **5. Always-On Banner**](#5.Always-OnBanner)
+    - 2.3.6. [✅ **6. Empty Banner**](#6.EmptyBanner)
+  - 2.4. [📝 How to submit a PR for Banner](#HowtosubmitaPRforBanner)
+  - 2.5. [✅ UI Behavior](#UIBehavior)
+  - 2.6. [❓ Frequently Asked Questions](#FrequentlyAskedQuestions)
+- 3. [📢 System Notifications](#SystemNotifications)
+  - 3.1. [✅ **Notification JSON Format**](#NotificationJSONFormat)
+  - 3.2. [✅ **Example Notification ConfigMap**](#ExampleNotificationConfigMap)
+  - 3.3. [✅ **Notification Content Validation**](#NotificationContentValidation)
+  - 3.4. [✅ **Folder Structure**](#FolderStructure)
+  - 3.5. [✅ **UI Behavior**](#UIBehavior-1)
+  - 3.6. [✅ **When to Add or Remove Notifications**](#WhentoAddorRemoveNotifications)
+
 # 🚀 konflux-info Repository Guide
 
-## 📂 Directory Structure
+## 1. <a name='DirectoryStructure'></a>📂 Directory Structure
 
 The `KONFLUX-INFO` directory contains:
 
 ```bash
 .
-├── auto-alert-schema.json  # JSON shema definition for auto-alert-content.yaml
 ├── base/                   # Common resources (e.g., RBAC)
 ├── production/             # Production cluster configurations
 ├── staging/                # Staging cluster configurations
 ├── banner-schema.json      # JSON schema definition for validating banner-content.yaml files
-
+├── notification-schema.json      # JSON schema definition for validating notification-content.json
 ```
 
 Each cluster directory contains:
 
 ```bash
 .
-├── auto-alerts # The directory manages auto-generated alerts content shown in the UI
+├── system-notifications # The directory manages auto-generated notifications content shown in the UI
 ├── banner-content.yaml # The banner content shown in the UI
 ├── info.json # Metadata about the cluster
-└── kustomization.yaml # Kustomize configuration for this cluster, including base, auto-alerts, and other configs
+└── kustomization.yaml # Kustomize configuration for this cluster, including base, system-notifications, and other configs
 
 ```
 
 ---
 
-## ✅ Banner Content Validation
+## 2. <a name='KonfluxBanner'></a>📢 Konflux Banner
+
+### 2.1. <a name='BannerContentValidation'></a>✅ Banner Content Validation
 
 To maintain consistency, a GitHub workflow named **`banner-validate`** automatically validates all `banner-content.yaml` files against the schema defined in [`banner-schema.json`](./banner-schema.json).
 
@@ -47,26 +74,19 @@ To maintain consistency, a GitHub workflow named **`banner-validate`** automatic
 - Review the error message in the PR checks.
 - Compare your changes with the [schema](./banner-schema.json) and [examples in README](#usage-scenarios--examples).
 
-## ✅ Banner Content Specification
+### 2.2. <a name='BannerContentSpecification'></a>✅ Banner Content Specification
 
 The `banner-content.yaml` file defines one or more banners displayed in the Konflux UI. Each cluster has its own `banner-content.yaml` under its directory (e.g., `staging/stone-stage-p01/banner-content.yaml`).
 
-### **Schema**
+#### 2.2.1. <a name='Schema'></a>**Schema**
 
 The schema for banner content is defined in [`banner-schema.json`](./banner-schema.json) and validated automatically by the `banner-validate` GitHub workflow on every PR.
 
 The file must contain a **YAML list** where each item represents a banner configuration.
 
 ---
 
-### **Important Behavior**
-
-- The <strong style="color: red;">UI displays only the first valid active banner</strong> from the list, based on current date, time, and optional recurrence settings.
-- If multiple banners are configured, <strong style="color: red;">order matters</strong>.
-
----
-
-### **Required and Optional Fields for Each Banner**
+#### 2.2.2. <a name='RequiredandOptionalFieldsforEachBanner'></a>**Required and Optional Fields for Each Banner**
 
 📎 For the full schema used in CI validation, see banner-schema.json. This table is a human-friendly reference for banner authors.
 
@@ -86,9 +106,9 @@ The file must contain a **YAML list** where each item represents a banner config
 
 ---
 
-### **Usage Scenarios & Examples**
+### 2.3. <a name='UsageScenariosExamples'></a>Usage Scenarios & Examples
 
-#### ✅ **1. Multiple Banners**
+#### 2.3.1. <a name='1.MultipleBanners'></a>✅ **1. Multiple Banners**
 
 Example of a `banner-content.yaml` with multiple banners (first active one is shown in UI):
 
@@ -110,7 +130,7 @@ Example of a `banner-content.yaml` with multiple banners (first active one is sh
   # No timezone is needed when you expect it's UTC.
 ```
 
-#### ✅ **2. One-Time Banner**
+#### 2.3.2. <a name='2.One-TimeBanner'></a>✅ **2. One-Time Banner**
 
 For a single event on a specific date:
 
@@ -133,7 +153,7 @@ For a single event in today
   endTime: "14:00"
 ```
 
-#### ✅ **2. Weekly Recurring Banner**
+#### 2.3.3. <a name='3.WeeklyRecurringBanner'></a>✅ **3. Weekly Recurring Banner**
 
 For an event that repeats every week:
 
@@ -145,7 +165,7 @@ For an event that repeats every week:
   endTime: "04:00"
 ```
 
-#### ✅ **3. Monthly Recurring Banner**
+#### 2.3.4. <a name='4.MonthlyRecurringBanner'></a>✅ **4. Monthly Recurring Banner**
 
 For an event that happens on the same day each month:
 
@@ -158,7 +178,7 @@ For an event that happens on the same day each month:
   timeZone: "Asia/Shanghai"
 ```
 
-#### ✅ **4. Always-On Banner**
+#### 2.3.5. <a name='5.Always-OnBanner'></a>✅ **5. Always-On Banner**
 
 For an event that requires immediate notification:
 
@@ -167,7 +187,7 @@ For an event that requires immediate notification:
   type: "info"
 ```
 
-#### ✅ **5. Empty Banner**
+#### 2.3.6. <a name='6.EmptyBanner'></a>✅ **6. Empty Banner**
 
 When there are no events to announce:
 
@@ -177,7 +197,7 @@ When there are no events to announce:
 
 ---
 
-## 📝 How to submit a PR for Banner
+### 2.4. <a name='HowtosubmitaPRforBanner'></a>📝 How to submit a PR for Banner
 
 1. Locate the target cluster directory:
 
@@ -225,7 +245,18 @@ When there are no events to announce:
   Purpose: Release announcement for Konflux 1.2
   ```
 
-## ❓ Frequently Asked Questions
+### 2.5. <a name='UIBehavior'></a>✅ UI Behavior
+
+- The <strong style="color: red;">UI displays only the first valid active banner</strong> from the list, based on current date, time, and optional recurrence settings.
+- If multiple banners are configured, <strong style="color: red;">order matters</strong>.
+- <strong style="color: red;">Time-related fields like `startTime` and `endTime` are not displayed in the UI</strong>; they only control when the banner is active.
+
+  <strong>To convey duration or timing details, please include them within the `summary`.</strong>
+
+- <strong style="color: red;">The `type` and `summary` fields are displayed directly in the UI</strong>.
+- We enjoyed leveraging the [PatternFly Banner component (v5)](https://v5-archive.patternfly.org/components/banner/) to implement the UI, following its design principles for clarity and consistency.
+
+### 2.6. <a name='FrequentlyAskedQuestions'></a>❓ Frequently Asked Questions
 
 - Why is only one banner shown even when multiple are configured?
 
@@ -245,41 +276,125 @@ When there are no events to announce:
 
   <strong style="color: red;">📝 If multiple messages need to be shared at the same time, consider combining them into a well-written summary inside a single banner.</strong>
 
-## 📢 Auto Alerts(WIP)
+## 3. <a name='SystemNotifications'></a>📢 System Notifications
+
+The infrastructure team uses System Notifications to automatically surface important operational notifications in the Konflux UI.
+
+These notifications are generated from monitoring systems or automation scripts as Kubernetes ConfigMaps.
+
+The Konflux UI detects and displays these notifications to inform users about system-wide conditions.
+
+### 3.1. <a name='NotificationJSONFormat'></a>✅ **Notification JSON Format**
+
+System notifications are stored as Kubernetes ConfigMaps in the `system-notifications/` directory.
+
+Each ConfigMap contains notification data in the `notification-content.json` field as JSON.
+
+<strong>Key points:</strong>
+
+- The JSON payload supports these fields for each notification object:
+
+  - <strong>title (optional)</strong>: A short heading.
+  - <strong>summary (required)</strong>: A brief, user-facing message displayed as the notification content.
+  - <strong>type (required)</strong>: It sets the bell icon. Allowed values: `info`, `warning`, or `danger`.
+  - <strong>activeTimestamp (optional)</strong>: The time when the notification should be shown, specified as an ISO 8601 timestamp (e.g., `"2025-08-11T11:08:17Z"`).
+    - If set to a future time, the UI will delay displaying the notification until that time is reached.
+    - If not set, the system falls back to using the resource’s raw `creationTimestamp` to decide when to show the notification.
 
-We enables the infrastructure team to automatically surface specific operational issues or warnings in the Konflux UI.
+- Payload structure:
 
-These alerts would be auto-generated from monitoring systems or automation scripts, written as Kubernetes ConfigMaps, and automatically picked up by the Konflux UI to inform users of system-wide conditions.
+  We recommend using <strong>a single JSON object representing one notification</strong> in `notification-content.json`.
 
-### ✅ Alert YAML Format
+  However, <strong>a JSON list (array) of notification objects is also allowed</strong> if multiple notifications need to be included in one ConfigMap.
 
-Each file under auto-alerts/ must be a valid Kubernetes ConfigMap, including at minimum:
+### 3.2. <a name='ExampleNotificationConfigMap'></a>✅ **Example Notification ConfigMap**
 
 ```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:
-  name: konflux-auto-alert-xyz
+  name: konflux-system-notification-xyz
   namespace: konflux-info
   labels:
-    konflux-auto-alert: "true" # Required. UI filter alerts out by this label.
+    konflux.system.notification: "true"
 data:
-  auto-alert-content.yaml: |
-    enable: true
-    summary: "Builds are delayed due to maintenance"
-    type: "warning"
+  notification-content.json: |-
+    {
+      "summary": "Builds are delayed due to maintenance",
+      "type": "warning",
+      "title": "From Builds Service",
+      "activeTimestamp": "2025-08-12T14:30:00Z"
+    }
 ```
 
-🔐 The data.banner-content.yaml should follow the schema defined in `auto-alert-schema.json`
+⚠️ `title` and `activeTimestamp` are optional fields. Include them only when necessary.
 
-### Folder Structure
+### 3.3. <a name='NotificationContentValidation'></a>✅ **Notification Content Validation**
+
+To ensure consistency, a GitHub workflow named `notification-validate` automatically checks that all ConfigMaps in the `system-notifications` folder include the required labels and validates all `notification-content.json` objects against the schema defined in [notification-schema.json](./notification-schema.json).
+
+**When does it run?**
+
+- On any pull request that changes:
+  - `notification-schema.json` (schema definition)
+  - Any `yaml` file defined under `system-notifications`
+
+**What does it check?**
+
+- Ensures the JSON structure matches the schema (e.g., required fields, allowed values).
+- Ensure the configmaps are labelled well.
+- Prevents invalid or misconfigured notifications from being merged.
+
+**How to fix validation errors?**
+
+- Review the error message in the PR checks.
+- Compare your changes with the [schema](./notification-schema.json) and your labels.
+
+### 3.4. <a name='FolderStructure'></a>✅ **Folder Structure**
+
+Notifications are organized under the `system-notifications/` directory:
 
 ```bash
 
-auto-alerts/   # Alert ConfigMaps (one file = one alert)
+system-notifications/
 .
-├── alert-1.yaml           # Fully valid ConfigMap YAML
-├── alert-2.yaml
-└── kustomization.yaml     # Auto-generated, includes all alert YAMLs
+├── notification-1.yaml  # A ConfigMap representing one notification
+├── notification-2.yaml
+└── kustomization.yaml   # Auto-generated, includes all notifications YAMLs
 
 ```
+
+When there are no active notifications, both the `system-notifications/` folder and its reference in the parent `kustomization.yaml` should be removed automatically to avoid kustomize errors.
+
+### 3.5. <a name='UIBehavior-1'></a>✅ **UI Behavior**
+
+- The UI discovers and filters notifications by detecting ConfigMaps labeled with
+  `konflux.system.notification: "true".`
+- When a valid notification ConfigMap exists, its notification will be shown in the UI only if the active time has been reached.
+- The UI respects the `activeTimestamp` field to control when notifications are displayed:
+  - If `activeTimestamp` is set to a future time, the notification remains hidden until that time arrives.
+  - If `activeTimestamp` is not set, the notification uses the resource's `creationTimestamp` to determine when to show.
+- To remove a notification from the UI, the corresponding ConfigMap must be deleted or renamed so it no longer matches the label.
+- When multiple notifications exist, the UI lists them ordered by their active time, <strong>showing the most recent first</strong>.
+- The `type` field control the notification icon shown before the title in the Notification Drawer.
+- If the `title` field is omitted in the JSON, it falls back to using component.metadata.name as the default in the UI.
+- We leveraged [PatternFly Notification Drawer (v5)](https://v5-archive.patternfly.org/components/notification-drawer/html/#ws-core-c-notification-drawer-basic) and [Notification Badge (v5)](https://v5-archive.patternfly.org/components/notification-badge) components to implement the UI, following their design principles for consistency and usability.
+- All notifications are always shown as unread. There is no backend tracking for notification state, so <strong>`read/unread` functionality is not supported</strong>.
+
+### 3.6. <a name='WhentoAddorRemoveNotifications'></a>✅ **When to Add or Remove Notifications**
+
+<strong>These notification ConfigMaps are automatically generated or removed</strong> by monitoring or scripting systems based on current system status.
+
+- Add a notification:
+
+  1. Generate a new ConfigMap YAML file under `system-notifications/`.
+  2. Refresh the `kustomization.yaml` in that folder to include the new file.
+  3. If the folder does not exist (e.g., no prior notifications), create it and its `kustomization.yaml`, and ensure the parent kustomization includes it.
+
+- Remove a notification:
+
+  1. Delete the corresponding ConfigMap YAML file from `system-notifications/`.
+  2. Refresh `kustomization.yaml` to remove the reference.
+  3. If no notifications remain, delete the `system-notifications/` directory and remove its reference from the parent kustomization.
+
+⚠️ <strong>These add/remove operations are expected to be automated</strong>. Manual edits should only be done in emergencies or for debugging.