Visual Diff Merge

A powerful visual diff and merge tool for the web

Architecture Overview

Visual Diff Merge is built with a modular architecture that separates backend processing from frontend visualization. This separation allows for flexibility in deployment and usage scenarios while maintaining a consistent user experience.

Figure 1: High-level architecture of Visual Diff Merge

The system is composed of three main layers:

  1. Backend (PHP): Handles file operations, diff generation, and security
  2. API Layer: Provides endpoints for diff processing, file access, and configuration
  3. Frontend (JavaScript): Manages UI components, visualization, and user interactions

For implementation details about configuring these components, see the Configuration section of the Installation guide.

System Components

Backend Components

The backend is implemented in PHP and provides core functionality for file operations, diff generation, and security.

Component Description Responsibilities
DiffViewer Core diff generation engine
  • Generate diff data between content sources
  • Process files, URLs, and raw text content
  • Format diff results for frontend consumption
FileBrowser File system interaction
  • Scan directories for available files
  • Read file contents safely
  • Provide hierarchical file organization
Config Configuration management
  • Load and merge configuration settings
  • Provide access to settings via consistent API
  • Generate client-side configuration subset
PathManager Secure path handling
  • Generate secure file references
  • Map reference IDs to real file paths
  • Maintain path security across requests
Security Security services
  • Validate file paths and access permissions
  • Sanitize inputs and prevent exploits
  • Enforce directory access restrictions
DebugLogger Logging functionality
  • Record diagnostic information
  • Support multiple log levels
  • Format complex data for debugging

API Layer Components

The API layer consists of several endpoint scripts that handle specific functionality and bridge the frontend with the backend.

Endpoint Description Responsibilities
diff-processor.php Primary diff processing endpoint
  • Process content from various sources
  • Generate diff data using DiffViewer
  • Return formatted results to client
ajax-diff-merge.php Merge operation handler
  • Process merge requests
  • Save merged content to files
  • Handle various save options (original, suffix, etc.)
get-file-content.php Secure file content provider
  • Retrieve file content safely
  • Validate file references and permissions
  • Return file content in standardized format
get-url-content.php URL content fetcher
  • Retrieve content from external URLs
  • Bypass client-side CORS restrictions
  • Handle errors and timeout gracefully
endpoint-config.php Configuration provider
  • Return client-side configuration settings
  • Provide language and translation data
  • Share debug settings with client
endpoints-config.php API discovery service
  • Provide endpoint URLs to client
  • Support relative or absolute URL formats
  • Enable dynamic endpoint discovery

Frontend Components

The frontend is built with modular JavaScript components that handle visualization, user interaction, and state management.

Component Description Responsibilities
DiffViewer Main viewer component
  • Coordinate visualization of diff content
  • Manage subcomponents and services
  • Handle initialization and state management
ChunkManager Chunk handling and rendering
  • Process diff chunks for display
  • Manage chunk selection and state
  • Coordinate visual representation of chunks
MergeHandler Merge operations controller
  • Process user merge selections
  • Generate merged content
  • Handle save operations and API interactions
DiffNavigator Navigation controls
  • Provide next/previous navigation
  • Track current position in diff
  • Show navigation indicators
SyntaxHighlighter Code highlighting
  • Detect languages automatically
  • Apply syntax highlighting to code
  • Manage highlight.js integration
ThemeManager Theme handling
  • Switch between light and dark modes
  • Manage highlighting themes
  • Persist user theme preferences
Mode-specific Managers Mode controllers
  • Handle specific mode functionality (FileBrowserManager, FileUploadManager, etc.)
  • Coordinate API interactions for specific modes
  • Manage mode-specific UI elements
Utility Classes Shared services
  • Provide common functionality (Debug, DOMUtils, etc.)
  • Implement core services (AlertManager, LoaderManager, etc.)
  • Enable shared state management

Data Flow

The data flow in Visual Diff Merge varies depending on the operation mode, but follows a general pattern:

Figure 2: Data flow across system components

General Data Flow Sequence

  1. Content Acquisition: Content is obtained from the source (files, URLs, or direct input)
  2. Content Processing: Content is sent to the API for diff generation
  3. Diff Calculation: The backend processes the content and generates diff data
  4. Diff Visualization: The frontend renders the diff data in the viewer
  5. User Interaction: Users navigate, select chunks, and make merge decisions
  6. Merge Processing: Selected merge operations are processed by the API (if applicable)
  7. Result Delivery: Merged content is saved or returned to the user

Mode-Specific Workflows

File Browser Mode

  1. User → FileBrowserManager: Select files for comparison
  2. FileBrowserManager → get-file-content.php: Request file content using file references
  3. get-file-content.php → PathManager: Resolve file paths from references
  4. PathManager → Security: Validate file access permissions
  5. get-file-content.php → FileBrowserManager: Return file content
  6. FileBrowserManager → diff-processor.php: Send content for diff processing
  7. diff-processor.php → DiffViewer (PHP): Process content and generate diff
  8. diff-processor.php → FileBrowserManager: Return diff data and configuration
  9. FileBrowserManager → DiffViewer (JS): Initialize viewer with diff data
  10. DiffViewer (JS): Render diff visualization and UI components

File Upload Mode

  1. User → FileUploadManager: Upload files for comparison
  2. FileUploadManager: Read file content from uploaded files
  3. FileUploadManager → diff-processor.php: Send content for diff processing
  4. diff-processor.php → DiffViewer (PHP): Process content and generate diff
  5. diff-processor.php → FileUploadManager: Return diff data and configuration
  6. FileUploadManager → DiffViewer (JS): Initialize viewer with diff data
  7. DiffViewer (JS): Render diff visualization and UI components

Text Compare Mode

  1. User → TextCompareManager: Input text for comparison
  2. TextCompareManager → diff-processor.php: Send text content for diff processing
  3. diff-processor.php → DiffViewer (PHP): Process content and generate diff
  4. diff-processor.php → TextCompareManager: Return diff data and configuration
  5. TextCompareManager → DiffViewer (JS): Initialize viewer with diff data
  6. DiffViewer (JS): Render diff visualization and UI components

URL Compare Mode

  1. User → UrlCompareManager: Input URLs for comparison
  2. UrlCompareManager → get-url-content.php: Request URL content for client-side preview (optional)
  3. UrlCompareManager → diff-processor.php: Send URLs for diff processing
  4. diff-processor.php: Fetch content from URLs
  5. diff-processor.php → DiffViewer (PHP): Process content and generate diff
  6. diff-processor.php → UrlCompareManager: Return diff data and configuration
  7. UrlCompareManager → DiffViewer (JS): Initialize viewer with diff data
  8. DiffViewer (JS): Render diff visualization and UI components

Mode-Specific Data Flows

Visual Diff Merge supports four primary modes of operation, each with its own data flow pattern. These diagrams illustrate how data moves through the system in each operational mode.

File Browser Mode

File Browser mode allows users to navigate the server's file system and select files for comparison.

Figure 5: Data flow in File Browser mode

File Upload Mode

File Upload mode enables users to upload files from their local system for comparison.

Figure 6: Data flow in File Upload mode

Text Compare Mode

Text Compare mode allows direct comparison of text snippets entered by users.

Figure 7: Data flow in Text Compare mode

URL Compare Mode

URL Compare mode fetches content from remote URLs for comparison.

Figure 8: Data flow in URL Compare mode

Initialization Sequence

The initialization sequence describes how the application bootstraps itself when a page is loaded. This process includes loading configuration settings, initializing components, and preparing the UI.

Figure 9: Application initialization sequence

During initialization, the following steps occur:

  1. DOM content load triggers the application bootstrap
  2. Configuration is loaded from default and user settings
  3. Theme preferences are applied
  4. Core components are initialized
  5. Mode-specific components are loaded based on the current view
  6. Event listeners are attached to UI elements
  7. Initial state is established

Configuration Flow

Visual Diff Merge uses a cascading configuration system that merges defaults with user preferences and runtime settings. This ensures flexibility while maintaining consistent behavior.

Figure 10: Configuration resolution flow

The configuration system processes settings in this order of precedence:

  1. Runtime settings (highest priority)
  2. URL parameters
  3. User preferences (stored in localStorage)
  4. Instance configuration (server-side settings)
  5. Default configuration (lowest priority)

This hierarchical approach allows for flexible customization while ensuring the application always has valid settings to fall back on.

Extension Points

Visual Diff Merge is designed with extensibility in mind. The application provides several extension points where developers can customize behavior without modifying the core codebase.

Syntax Highlighting

The SyntaxHighlighter component supports custom language definitions and themes beyond the built-in options provided by highlight.js.

Diff Algorithms

The core differencing engine can be extended with custom algorithms by implementing the appropriate interfaces in the DiffViewer component.

Custom Themes

The ThemeManager supports registration of custom themes that can be added to the theme selection options available to users.

Custom File Sources

Beyond the built-in file sources (browser, upload, text, URL), developers can implement custom file sources by extending the appropriate base classes and registering them with the application.

Conclusion

This architectural overview provides a high-level understanding of Visual Diff Merge's design and component structure. For implementation details, refer to the source code and inline documentation. For customization options, see the Customization guide.

Last updated: April 21, 2025