Process Flow Mapper

A React application for visualizing business processes with integrated metrics tracking. Built with React Flow and Chart.js.

Quick Start

npm install
npm run dev

Open http://localhost:5173 to see the app.

What you'll see:

• Process flow with steps and decision points
• Process metrics panel at the top with WoW trends
• Clickable steps that drill down into sub-processes
• Sparkline charts on all metrics

Try this:

1. Click "Step 2" to see the drill-down detail modal
2. Edit src/data/processes/main-process.json and refresh to see changes
3. Modify CSS files to customize appearance

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Data Layer                               │
│   ┌─────────────────────┐    ┌─────────────────────┐           │
│   │ Process JSON Files  │    │   Metrics Data      │           │
│   │ (src/data/processes)│    │   (mockMetrics.json)│           │
│   └──────────┬──────────┘    └──────────┬──────────┘           │
└──────────────┼──────────────────────────┼───────────────────────┘
               │                          │
               ▼                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Application Layer                           │
│                      ┌─────────────┐                             │
│                      │   App.jsx   │                             │
│                      │   (State)   │                             │
│                      └──────┬──────┘                             │
└─────────────────────────────┼───────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ProcessMetrics│    │ ProcessFlow  │    │ DetailModal  │
│    Panel     │    │              │    │              │
└──────┬───────┘    └──────┬───────┘    └──────────────┘
       │                   │
       ▼                   ▼
┌──────────────┐    ┌──────────────┐
│  MetricCard  │    │   StepNode   │
│  (Chart.js)  │    │ (React Flow) │
└──────────────┘    └──────────────┘

Data Flow

1. Load: App loads process JSON and metrics data
2. Transform: Data helpers convert JSON to React Flow format
3. Render: Components receive data as props
4. Interact: User clicks step -> loads detail process -> shows modal

Component Hierarchy

App
├── ProcessMetricsPanel
│   └── MetricCard (multiple) -> Chart.js sparklines
├── ProcessFlow
│   └── StepNode (multiple) -> React Flow nodes
└── DetailModal (conditional)
    ├── ProcessMetricsPanel
    └── ProcessFlow

---

Project Structure

process-flow-app/
├── index.html                    # HTML entry point
├── package.json                  # Dependencies
├── vite.config.js               # Build config
├── README.md                    # This file
├── JSON_SCHEMA.md               # Process JSON reference
├── ARCHITECTURE.svg             # Visual diagram
│
└── src/
    ├── main.jsx                 # React entry point
    ├── App.jsx                  # Main component (state management)
    ├── App.css                  # Global styles
    │
    ├── components/
    │   ├── ProcessFlow/         # React Flow canvas
    │   │   ├── ProcessFlow.jsx
    │   │   └── ProcessFlow.css
    │   ├── StepNode/            # Individual process steps
    │   │   ├── StepNode.jsx
    │   │   └── StepNode.css
    │   ├── MetricCard/          # Metric display with charts
    │   │   ├── MetricCard.jsx
    │   │   └── MetricCard.css
    │   ├── ProcessMetricsPanel/ # Container for process metrics
    │   │   ├── ProcessMetricsPanel.jsx
    │   │   └── ProcessMetricsPanel.css
    │   └── DetailModal/         # Drill-down overlay
    │       ├── DetailModal.jsx
    │       └── DetailModal.css
    │
    ├── data/
    │   ├── processes/           # Process definitions (JSON)
    │   │   ├── main-process.json
    │   │   ├── step-2-detail.json
    │   │   ├── ticket-resolution.json
    │   │   └── triage-detail.json
    │   └── mockMetrics.json     # Sample metrics data
    │
    └── utils/
        ├── dataHelpers.js       # Load processes, get metric values
        ├── processTransform.js  # Transform JSON to React Flow
        └── useProcessData.js    # Custom React hook

---

Visual Layout

Main View

┌─────────────────────────────────────────────────────────────┐
│  Process Flow Mapper                                         │
│  Process description here                                    │
├─────────────────────────────────────────────────────────────┤
│  Process Metrics                                             │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │ Metric Name     │  │ Total Volume    │                   │
│  │ 87.5%           │  │ 1,247           │                   │
│  │ ↑ 2.7% WoW     │  │ ↑ 4.9% WoW     │                   │
│  │ ▁▂▃▂▄▅▅        │  │ ▂▃▄▃▅▆▆        │                   │
│  └─────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│                    ┌───────────┐                            │
│                    │  Step 1   │ (action)                   │
│                    └─────┬─────┘                            │
│                          │                                   │
│                          ▼                                   │
│                    ┌───────────┐                            │
│                    │ Step 2  → │ (clickable)                │
│                    └─────┬─────┘                            │
│                          │                                   │
│                          ▼                                   │
│                    ┌───────────┐                            │
│                    │ Decision  │ (decision point)           │
│                    └───┬───┬───┘                            │
│                   ┌────┘   └────┐                           │
│                   ▼             ▼                            │
│            ┌──────────┐  ┌──────────┐                       │
│            │ Step 3.1 │  │ Step 3.2 │                       │
│            └──────────┘  └──────────┘                       │
│                                                              │
│     [Zoom Controls]  [Mini-map]                             │
└─────────────────────────────────────────────────────────────┘

Detail Modal (click a step with drill-down)

╔═══════════════════════════════════════════════════════════════╗
║  Step 2 - Detailed View                                    X  ║
║  Detailed breakdown of the step                               ║
╠═══════════════════════════════════════════════════════════════╣
║                    ┌──────────┐                               ║
║                    │ Step 2.1 │                               ║
║                    └────┬─────┘                               ║
║                         ▼                                     ║
║                    ┌──────────┐                               ║
║                    │ Step 2.2 │                               ║
║                    └────┬─────┘                               ║
║                         ▼                                     ║
║                    ┌──────────┐                               ║
║                    │ Step 2.3 │                               ║
║                    └──────────┘                               ║
╚═══════════════════════════════════════════════════════════════╝
        Click outside or X to close

---

JSON Schema (Quick Reference)

See JSON_SCHEMA.md for complete documentation.

Process Definition

{
  "processId": "my-process",
  "name": "Process Name",
  "description": "What this process does",
  "processMetrics": [
    {
      "id": "metric-1",
      "name": "Metric Name",
      "type": "percentage",
      "dataSource": "metrics.path.to.data"
    }
  ],
  "steps": [
    {
      "id": "step-1",
      "name": "Step Name",
      "type": "action",
      "description": "What happens here",
      "hasDetail": false,
      "stepMetrics": []
    },
    {
      "id": "step-2",
      "name": "Drill-down Step",
      "type": "decision",
      "description": "This step has sub-process",
      "hasDetail": true,
      "detailProcessId": "step-2-detail",
      "stepMetrics": []
    }
  ]
}

Metrics Data

{
  "metrics": {
    "path": {
      "to": {
        "data": {
          "current": 87.5,
          "previous": 85.2,
          "trend": "up",
          "weeklyData": [82, 83, 85, 84, 86, 88, 87.5]
        }
      }
    }
  }
}

Step Types

• action - Standard process step (green styling)
• decision - Branching/conditional logic (blue styling)

Metric Types

• count - Quantities (1,234)
• percentage - Rates (87.5%)
• duration - Time periods (5.2 hours)
• rate - Scores/indexes (42.7)

---

Customization

Change Process Structure

Edit JSON files in src/data/processes/:

{
  "steps": [
    { "id": "new-step", "name": "My New Step", ... }
  ]
}

Change Styling

Step appearance: src/components/StepNode/StepNode.css

.step-node-action {
  border-color: #10b981;  /* Change to green */
}

Metric cards: src/components/MetricCard/MetricCard.css

Layout spacing: Adjust yPosition increments in ProcessFlow.jsx

Connect Real Data

Replace mock data in src/utils/dataHelpers.js:

export const loadMetrics = async () => {
  const response = await fetch('/api/metrics');
  return response.json();
};

---

Component API

ProcessFlow

<ProcessFlow
  processData={processDefinition}
  onStepClick={(step) => handleClick(step)}
/>

StepNode

<StepNode
  data={{
    step: stepObject,
    onClick: handleStepClick
  }}
/>

MetricCard

<MetricCard
  metric={metricDefinition}
  metricData={metricValues}
/>

ProcessMetricsPanel

<ProcessMetricsPanel
  processMetrics={processMetricsArray}
  metricsData={metricsDataObject}
/>

---

Technologies

• React 18 - UI framework
• React Flow 11 - Flow diagram visualization
• Chart.js 4 - Metric charts
• Vite 5 - Build tool

---

Roadmap

Phase 1: Styling

• Refine color scheme
• Add icons for step types
• Improve responsive design

Phase 2: Data Integration

• Connect to API
• Add data refresh
• Loading/error states

Phase 3: Features

• URL routing for deep linking
• Search/filter for large processes
• Export (PDF, image)

Phase 4: Editing

• Visual process editor
• Version control
• Collaboration features

---

Key Files to Edit

Task	File
Change process structure	src/data/processes/*.json
Update metrics data	src/data/mockMetrics.json
Change step styling	src/components/StepNode/StepNode.css
Change metric styling	src/components/MetricCard/MetricCard.css
Change layout logic	src/components/ProcessFlow/ProcessFlow.jsx
Connect real data	src/utils/dataHelpers.js

---

Design Principles

1. JSON as Source of Truth - Processes defined in data, not code
2. Component Reusability - Building blocks recombined for different views
3. Data Separation - Process structure separate from metric values
4. Progressive Enhancement - Start simple, add features incrementally