Integrate the model graph tools into halOP

[hpehl]

Blueprint: halOP & Model Graph Tools (MGT) Integration Design

1. Executive Summary

This document serves as an architectural blueprint for integrating Model Graph Tools (MGT) into halOP (the next-generation management console for WildFly).

Instead of rebuilding complex graphical visualization frontends within the browser or bundling massive, static datasets inside the console application, this design patterns the integration as a Sidecar Knowledge Base. halOP queries a running, version-matched MGT Neo4j container via a REST/HTTP endpoint to enable advanced semantic search, cross-reference capabilities, and instant deep-linking into the appropriate configuration spaces within the console.

---

2. Architectural Architecture: The Sidecar Pattern

In production and development environments alike, halOP remains completely stateless and lightweight, communicating with the target WildFly instance over standard DMR/HTTP.

When an administrator deploys the corresponding versioned MGT container (e.g., via Podman or Docker using mgt start <version>), halOP discovers this optional endpoint and treats it as a read-only, high-performance schema index.

                  ┌────────────────────────────────────────┐
                  │          MGT Neo4j Container           │
                  │   (Pre-indexed Versioned Model Schema)  │
                  └───────────────────┬────────────────────┘
                                      │
                                      │ HTTP / Cypher (JSON)
                                      ▼
┌──────────────────┐   DMR/HTTP    ┌───────────────────────┐
│ Target WildFly   ◄──────────────►│   halOP Console       │
│ Runtime Instance │               │ (Browser-based / J2CL)│
└──────────────────┘               └───────────────────────┘

Key Separation of Concerns

• WildFly Runtime: Manages the actual configuration state, server runtime, and execution of management operations.
• MGT Database: Contains the static metadata graph of the matching WildFly release (resources, attributes, operations, capabilities, and descriptions).
• halOP Browser App: Orchestrates the UI, queries the runtime for state, queries the graph for discoverability, and translates graph nodes into active UI navigation.

---

3. Search & Deep-Link Sequence Flow

The primary user interaction pattern is a global "Super Search" where semantic queries map straight to concrete configuration screens.

Scenario: Admin searches for a specific operational capability or attribute

1. Input: The user types max-post-size or a capability like org.wildfly.security.http-authentication-factory into the halOP global search bar.
2. Parallel Dispatch:
   • Local Dispatch: halOP queries the current runtime via DMR (for active deployment names, active server instances, etc.).
   • Graph Dispatch: halOP fires a Cypher JSON query over HTTP to the local MGT endpoint.
3. Graph Evaluation: The MGT instance scans its graph schema across resources, attributes, and capabilities.
4. Payload Return: The Neo4j container responds with matching nodes containing:
   • Element type (Attribute, Operation, Capability, Resource)
   • The text description / documentation
   • The absolute management model path (e.g., ["subsystem" => "undertow", "server" => "*", "http-listener" => "*"])
5. UI Rendering: halOP renders a distinct search result card highlighting the exact context.
6. Navigation: Clicking the result triggers halOP's router to map the management path into a Token/Presenter change, immediately highlighting the target input field.

---

4. Technical Strategy: Graph to UI Routing Map

To support seamless deep-linking, the MGT graph node attributes must align directly with WildFly's management path structure so that halOP can construct correct internal Presenter routes.

Path Normalization

MGT stores the structural tree of resources. When returning a node, it must include its absolute address array. halOP's routing engine converts this array into internal PlaceTokens:

Graph Path Element	Translated halOP Token / Presenter Route
/subsystem=undertow/server=*/http-listener=*	#undertow-server-listener;server=default-server
/subsystem=elytron/filesystem-realm=*	#elytron-realms;type=filesystem

Handling Wildcard vs. Concrete Instances

Because the MGT database tracks the static schema (what is structurally possible), its path components often contain wildcards (*). When a user deep-links:

1. halOP inspects the path subsystem=undertow, server=*, http-listener=*.
2. Before routing, halOP cross-references the running WildFly instance to fetch the actual names configured (e.g., server name is default-server).
3. If multiple instances exist, halOP prompts the user with a quick inline dropdown picker ("Which server instance do you want to configure? [default-server / public-server]") before executing the slide-in drawer or page transition.

---

5. UI/UX Integration Points

A. The "Super Search" Omnibar

• Integrate an extended results section in the top navigation search.
• Visual tagging: Clearly differentiate [Attribute], [Capability], and [Operation] results using distinct PatternFly label styles.

B. Inline Capability Explorer & "Where is this Used?" Drawer

• When editing a resource that requires a capability, halOP can display an informational icon.
• Clicking it queries MGT: MATCH (c:Capability {name: $cap})<-[:REQUIRES]-(r:Resource) RETURN r.
• Displays a side-drawer showing a clean list of other subsystems dependent on or provisioning that exact token, with one-click deep links to their configuration panels.

C. Graceful Degradation (Fallback Mode)

• On application startup, halOP sends a heartbeat or ping request to the configured MGT base URL (e.g., http://localhost:7474/db/data/ or a lightweight REST proxy endpoint).
• If Offline: The extended graph-search functionality is silently disabled or greyed out with a subtle tooltip ("Connect an MGT container to enable semantic cross-reference search"). No console errors break the core application.
• If Online: The search features light up automatically.

---

6. Critical Engineering Challenges & Mitigations

1. Cross-Origin Resource Sharing (CORS)

• The Problem: The halOP UI executes inside a browser sandbox served from WildFly's management port (e.g., 9990). Direct HTTP requests to an arbitrary Neo4j container port (e.g., 7474) will be rejected by browser security models.
• The Solution:
  1. Configure the MGT container launching script to inject CORS headers natively (dbms.security.allow_csv_import_from_file_urls=true, etc.).
  2. Alternatively, design a lightweight proxy gateway into the halOP standalone launcher if distributed together, or request users to map a simple reverse proxy path.

2. Version Synchronization

• The Problem: Querying a WildFly 40 model graph while managing a WildFly 34 runtime will result in misleading search results, broken links, or missing attribute references.
• The Solution: Upon connection, halOP reads the management model version from the local runtime container via a root DMR read-attribute operation, verifies it against the connected MGT database metadata version property, and shows a warning banner if a mismatch occurs.

---

7. Next Steps for Bootstrapping

1. Define the Cypher Payload Schema: Determine the exact JSON return shape for a generic full-text index query on the MGT Neo4j instance.
2. Prototype the Router Bridge: Write a utility class in halOP (MgtPathTranslator.java) that takes a standard DMR absolute path sequence and outputs a valid halOP PlaceRequest.
3. Draft the Search Elemento Component: Build a proof-of-concept dropdown list using Elemento that handles async callbacks from both the runtime and the external MGT REST endpoint simultaneously.