Reframe Package Visualizer

A web-based interactive visualization tool for exploring and understanding the structure of Reframe integration packages. This application provides both a workflow graph view and a field-level mapping visualization interface.

Features

Workflow View

• Interactive graph visualization showing package hierarchy:
  • Package root node
  • Workflow category nodes
  • Workflow tables with clickable rows
• Smooth zoom and pan controls
• Detailed workflow panel displaying:
  • Workflow metadata (ID, name, priority, description)
  • Condition expressions (JSONLogic)
  • Complete task breakdown with function details

Mapping View

• Interactive field tree visualization showing source and target fields
• Tree expansion/collapse for hierarchical field structures
• Field-level mapping connections with visual edges
• Three mapping types with distinct visual styling:
  • Direct mappings (blue) - Simple field-to-field mappings
  • Transform mappings (purple) - Mappings with data transformations
  • Conditional mappings (orange) - Mappings with conditional logic
• Search/filter functionality for fields
• Selection highlighting with automatic tree expansion

Additional Features

• Light and dark theme support with system preference detection
• Theme persistence using localStorage
• File system directory picker for loading packages (with fallback support)

Tech Stack

• React 19 - UI framework
• TypeScript 5 - Type-safe development
• Vite 7 - Build tool and dev server
• Material-UI (MUI) 7 - Component library
• XY Flow 12 - Node-based graph visualization
• Emotion - CSS-in-JS styling

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/your-org/Reframe-Package-Visualizer.git
cd Reframe-Package-Visualizer

# Install dependencies
npm install

Development

# Start the development server
npm run dev

The application will be available at http://localhost:5173

Build

# Create a production build
npm run build

# Preview the production build
npm run preview

Linting

npm run lint

Usage

1. Load a Package: Click the folder icon in the header to select a Reframe package directory. The package must contain a valid package.json with Reframe package metadata.

2. Workflow View: Navigate to the Workflow tab to see an interactive graph of the package structure. Click on workflow rows to view detailed information in the side panel.

3. Mapping View: Navigate to the Mapping tab to explore field mappings. Click on fields to see their connections. Use the search bar to filter fields.

Project Structure

src/
├── App.tsx                 # Root application component
├── main.tsx                # React app entry point
├── types/                  # TypeScript interfaces
│   ├── package.ts          # Package and workflow types
│   ├── workflow.ts         # Task and condition types
│   └── mapping.ts          # Field mapping types
├── contexts/               # React context providers
│   ├── PackageContext.tsx  # Package state management
│   └── ThemeContext.tsx    # Theme management
├── components/
│   ├── common/             # Shared UI components
│   ├── workflow/           # Workflow visualization
│   │   ├── WorkflowView.tsx
│   │   ├── TaskRenderer.tsx
│   │   └── nodes/          # Graph node components
│   └── mapping/            # Field mapping visualization
│       ├── MappingView.tsx
│       ├── MappingDetail.tsx
│       ├── nodes/          # Field tree nodes
│       └── edges/          # Mapping edge components
├── utils/                  # Utility functions
│   ├── fieldGrouping.ts    # Tree building utilities
│   └── jsonLogicParser.ts  # JSONLogic parsing
└── theme/                  # Theme definitions
    ├── lightTheme.ts
    └── darkTheme.ts

Reframe Package Format

The visualizer expects packages with the following structure:

{
  "id": "package-id",
  "name": "Package Name",
  "version": "1.0.0",
  "description": "Package description",
  "author": "Author Name",
  "license": "MIT",
  "engine": "1.0.0",
  "workflows": {
    "categoryName": [
      {
        "id": "workflow-id",
        "name": "Workflow Name",
        "condition": { /* JSONLogic expression */ },
        "tasks": [ /* task definitions */ ]
      }
    ]
  }
}

Deployment

The application is configured for automatic deployment to GitHub Pages. Every push to the main branch triggers a deployment workflow that:

1. Installs dependencies
2. Builds the production bundle
3. Deploys to GitHub Pages

To deploy manually:

# Build the project
npm run build

# The dist/ folder contains the production-ready files

The base URL is configured as /Reframe-Package-Visualizer/ in vite.config.ts for GitHub Pages compatibility.

License

This project is proprietary software. All rights reserved.