builder-prototype/ARCHITECTURE.md

Dispute Protocol Builder Architecture

This document explains the architectural decisions made in the Dispute Protocol Builder application.

Latest Architecture Update

The architecture has been significantly simplified to make it more maintainable and easier to extend.

Template System

The original architecture had a complex system of modules and templates:

1. Templates contained raw content
2. The template-mapper tried to match content to existing modules
3. If no match was found, it created custom modules
4. The builder would load templates and convert them to use module references

This approach became unnecessarily complex and had several drawbacks:

• Adding new templates required modifying multiple files
• The module matching logic was brittle and hard to maintain
• Many modules weren't actually reused across templates

New Simplified Architecture

The new architecture uses a direct template system:

1. Each template is stored in its own file in /static/js/templates/
2. Templates contain the full content for all stages and components
3. The index.js file imports and exports all templates
4. Templates are loaded dynamically in builder.js using ES Modules

The template loading process now follows these steps:

1. When the page loads, the fetchTemplates() function is called
2. The function dynamically imports the templates index file using ES modules
3. The templates are stored in memory and used to populate the dropdown
4. When a template is selected, the content is directly applied to the form fields

Benefits of this approach:

• Adding a new template is as simple as creating a new file and registering it in index.js
• No complex module matching logic or multiple data sources
• Clear 1:1 relationship between files and templates
• Easier to understand and maintain
• Improved error handling and debugging capabilities
• Single source of truth for template data

Template Loading Implementation

The core of the template loading is implemented in builder.js:

// Function to fetch templates - simplified approach
function fetchTemplates() {
  console.log('Fetching templates...');
  
  // Load all templates at startup
  try {
    import('/js/templates/index.js')
      .then(module => {
        templates = module.default;
        console.log('Templates loaded successfully:', templates.length, 'templates found');
        
        // Populate the template selector
        populateTemplateSelector(templates);
        
        // Add template selection event handler
        if (protocolTemplateSelect) {
          protocolTemplateSelect.addEventListener('change', handleTemplateSelection);
          console.log('Template selector event handler attached');
        } else {
          console.error('Template select element not found');
        }
      })
      .catch(error => {
        console.error('Error importing templates:', error);
      });
  } catch (e) {
    console.error('Error loading templates:', e);
  }
}

Simplified Component Names

All component titles have been simplified to be more direct and consistent:

• First-word capitalization only
• Short, descriptive phrases (2-3 words) instead of questions
• Example: "Process initiation" instead of "How does the process begin?"

Removed Components

The following components have been removed:

• YAML-based template configuration - No longer needed as templates are defined directly in JS
• Complex module mapper logic - Templates now contain direct content
• Module selection UI - Removed from the interface

Migration Process

To migrate a template from the old system to the new one:

1. Create a new file in /static/js/templates/
2. Copy the raw template structure from templates.js
3. Register the template in index.js

Future Considerations

If common content needs to be shared between templates in the future, standard JavaScript functions or objects can be used to generate that content without the overhead of the complex module system.

Core Components

The application is still built on the following core components:

1. Stage and Component Structure - Defined in YAML files
2. Templates - Complete predefined protocols stored in individual files
3. Builder Interface - Interactive UI for customizing protocols
4. Export System - Tools to export protocols in various formats

Adding New Features

When adding new features:

1. Keep the one-template-per-file architecture
2. Focus on the user experience of building and customizing protocols
3. Test thoroughly with multiple templates

For more details on implementation, see the README.md file.