Overview
Explain Plan is a visual debugging and analysis tool in Kodexa that shows how documents are processed step-by-step. Instead of wondering why data was extracted a certain way, you can see the exact sequence of processing steps, their inputs, outputs, and how they relate to each other.
What is Explain Plan?
Explain Plan is a visualization feature that:
Shows processing flow - Visual graph of all processing steps
Displays step details - Metadata, inputs, outputs for each step
Reveals relationships - How steps connect and flow
Enables debugging - Identify where processing succeeded or failed
Interactive exploration - Zoom, pan, and inspect individual steps
Example use case: A document processed through 15 steps: OCR, classification, multiple extraction models, validation, and export. Explain Plan shows this as a visual flow chart, letting you click each step to see what happened, what data was produced, and any errors encountered.
Accessing Explain Plan
From Document Processing
Open a processed document family
Navigate to processing history or details
Click Explain Plan
Visual flow graph appears
The Explain Plan Interface
Main Components
1. Toolbar
Fit to View - Centers and scales graph to fit viewport
Layout - Re-applies left-to-right hierarchical layout
Learn more - Link to this documentation
2. Graph Canvas
Visual flow diagram of processing steps
Nodes represent individual steps
Edges (arrows) show flow between steps
Pan by dragging, zoom with controls or mouse wheel
3. MiniMap
Small overview in bottom-left corner
Shows entire graph with current viewport
Click to navigate to different areas
Useful for large, complex processing flows
4. Zoom Controls
Bottom-left corner
Zoom in (+), Zoom out (-), Fit view buttons
Supports zoom range 0.01× to 4×
5. Properties Panel
Right side (collapsible)
Shows details for selected step
Initially collapsed
Opens when you click a step node
Understanding the Graph
Nodes (Processing Steps)
Each node in the graph represents a processing step:
Node label - Name of the processing step
Visual design - Styled cards with borders
Metadata preview - Key information visible on node
Click interaction - Click to view full details
Zoom interaction - Double-click or use zoom button to focus
Edges (Processing Flow)
Arrows connecting nodes show flow:
Direction - Shows which step outputs to which
Smooth curves - Easy-to-follow smoothstep edges
Multiple connections - Steps can have multiple parents or children
Hierarchical layout - Left-to-right flow by default
Layout Organization
Graph uses left-to-right hierarchical layout:
Earlier steps appear on the left
Later steps appear on the right
Parallel steps appear at same horizontal level
Clear flow from start to finish
Navigating the Graph
Panning
Click and drag on empty canvas
Move around large graphs
Cursor changes to hand when over pannable area
Zooming
Multiple zoom methods:
Mouse wheel - Scroll to zoom in/out
Zoom controls - Click + or - buttons
Fit to View - Auto-scale to see entire graph
Node zoom - Focus on specific node
Selecting Nodes
Click any node in the graph
Properties panel opens automatically
Panel shows full step metadata
Collapsed panel expands if needed
Zoom to Node
Click zoom button on a node (if available)
Graph zooms to focus on that node
Node centered with increased zoom (12× factor)
Click pane background to zoom out
Smooth animations (800ms duration)
Step Properties Panel
Viewing Step Details
When you click a node:
Properties panel slides open from right
Shows complete step metadata
Scrollable for long content
Stays open until you collapse it
Information Displayed
Step properties include:
Step name - Identifier for this processing step
Metadata - All data associated with the step
Configuration - Settings used for this step
Results - Output from the step
Timing - How long the step took
Status - Success, failure, or other state
Empty State
When no node is selected:
Shows "No Selected Step" message
Icon and instructions to select a step
Panel remains open but shows placeholder
Common Workflows
Debugging Failed Processing
Scenario: Document processing failed, need to find why
Steps:
Open Explain Plan for the failed document
Scan graph for error indicators (if shown)
Click each step in sequence
Review properties to find failure point
Check step inputs/outputs for issues
Identify which model or configuration caused failure
Understanding Processing Flow
Scenario: Want to understand how document was processed
Steps:
Open Explain Plan
Click "Fit to View" to see entire flow
Identify starting nodes (leftmost)
Follow arrows to see sequence
Click nodes to see what each step did
Understand overall processing pipeline
Comparing Processing Results
Scenario: Compare how two documents were processed
Steps:
Open Explain Plan for first document
Note the processing steps and results
Open Explain Plan for second document
Compare step sequences
Identify differences in flow or results
Determine why processing differed
Optimizing Processing Pipeline
Scenario: Processing is slow, need to optimize
Steps:
Open Explain Plan
Check timing data for each step (if available)
Identify slowest steps
Look for unnecessary steps
Find opportunities to parallelize
Adjust configuration based on findings
Advanced Features
Multiple Parents/Children
Processing steps can have:
Multiple parents - Step takes input from several previous steps
Multiple children - Step outputs to multiple next steps
Complex graphs - Parallel processing branches
Merging flows - Multiple streams combining
Graph Metadata Transformation
Raw processing data is transformed for display:
Arrays - Converted to comma-delimited strings
Objects - Formatted as JSON strings
Nested data - Flattened for readability
Clean format - Easier to read than raw data
Viewport Persistence
Graph remembers your view:
Current zoom level saved
Pan position preserved
Useful when switching between panels
Default: 0.4× zoom (40%)
Automatic Layout
Graph layout applied automatically:
Left-to-right hierarchical
Nodes positioned optimally
Edges routed to avoid overlap
Click "Layout" button to re-apply
Best Practices
Start with Fit to View - See entire flow before diving in
Follow the flow - Trace from left to right chronologically
Click to explore - Don't just look, interact with nodes
Use zoom strategically - Zoom in for details, out for overview
Check MiniMap - Navigate large graphs efficiently
Document findings - Note issues you discover for later
Compare similar documents - Learn patterns from comparisons
Focus on failures first - When debugging, find error nodes quickly
Performance Considerations
Large Graphs
For documents with many processing steps:
Use Fit to View to start
MiniMap helps navigate
Zoom to specific areas as needed
Graph virtualization handles large node counts
Smooth Animations
Optimized for performance:
800ms zoom animations (configurable)
Debounced layout updates (500ms)
Efficient re-rendering
Hardware-accelerated transforms
Dark Mode Support
Explain Plan adapts to dark mode:
Node backgrounds - Dark in dark mode
Node borders - Adjusted for visibility
Text color - Light in dark mode
Controls - Themed buttons and icons
Smooth transition - 0.2s ease animation
Troubleshooting
Graph Not Showing
Wait for processing steps to load
Click "Fit to View" to ensure graph is visible
Check that document has been processed
Verify explain plan data exists
Can't See Full Graph
Click "Fit to View" button
Use MiniMap to navigate
Zoom out with controls
Graph may be very large - pan to explore
Properties Panel Not Opening
Ensure you're clicking on a node (not edge or background)
Check that node is not in empty area
Panel may be collapsed - expand manually if needed
Try clicking "Layout" to refresh graph
Zoom Not Working
Try different zoom methods (wheel, controls, fit to view)
Check browser zoom isn't interfering
Ensure you're not at zoom limits (0.01× to 4×)
Click pane to exit node zoom mode
Technical Details
Built With Vue Flow
Explain Plan uses Vue Flow library:
Professional graph visualization
Interactive node-edge graphs
Rich customization options
Excellent performance
Node Types
Custom node type for processing steps:
Maximum width: 390px
Estimated height: 100px
Flexbox layout
Responsive design
Edge Configuration
Smooth step edges:
Curved connections
Automatic routing
Directional arrows
Clean visual flow
Tips
"Fit to View" centers entire graph with 0.5 padding
"Layout" button reapplies left-to-right hierarchical layout
Click nodes to open properties panel and view details
MiniMap in bottom-left helps navigate large graphs
Zoom controls support range from 0.01× to 4×
Click empty canvas while zoomed to zoom out
Properties panel collapses/expands automatically
Graph updates when processing steps change (debounced 500ms)
Smooth animations improve user experience (800ms zoom)
Dark mode automatically adjusts colors and contrast
Virtual scrolling handles very large processing graphs
Multiple parents/children show complex processing flows