builder-prototype/ARCHITECTURE.md

Dispute Protocol Builder Architecture

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

Current Architecture (2025)

The architecture has been completely redesigned to use a YAML-based template system with server-side rendering for maximum reliability and maintainability.

Evolution of Template System

Original Architecture: Complex JavaScript-based system with modules and template-mappers Previous Architecture: Direct ES module imports (had cross-platform compatibility issues) Current Architecture: YAML-based templates with Hugo server-side rendering

Current YAML-Based Template System

The new architecture completely eliminates client-side template loading issues:

1. Template Storage: All templates stored as YAML files in /data/templates/
2. Server-Side Rendering: Hugo renders template options directly into HTML at build time
3. Data Embedding: Template data embedded as JSON in the page for immediate JavaScript access
4. Event-Based Interaction: JavaScript adds click handlers to pre-rendered template options
5. Automatic Discovery: New templates automatically appear by simply adding YAML files

The template loading process now follows these steps:

1. During Hugo build, templates are rendered into HTML and data is embedded as JSON
2. When the page loads, JavaScript parses the embedded template data
3. Click handlers are attached to pre-rendered template options
4. When a template is clicked, content is directly applied to form fields
5. No client-side HTTP requests or ES module imports needed

Template Data Flow

YAML files → Hugo build → HTML + embedded JSON → JavaScript parsing → Form population
(/data/templates/)                (build time)                    (runtime)

Benefits of Current Architecture

Reliability:

• No client-side loading issues across different servers/browsers
• No CORS or ES module compatibility problems
• Works reliably in production environments

Maintainability:

• Templates stored as human-readable YAML
• Adding templates requires only creating a YAML file
• No complex JavaScript imports or registrations needed
• Version control friendly (YAML diffs are readable)

Performance:

• Templates loaded instantly at page load (no HTTP requests)
• Template options rendered at build time
• Faster user interaction (no loading delays)

Current Template Structure

Templates are stored in /data/templates/ as YAML files:

id: "template-id"
title: "Template Name"
description: "Brief description"

data:
  stages:
    basics:
      community_rules:
        communityRulesText: "Content with **markdown** support"
    # Full protocol structure

Core Data Structure

UI Structure: /data/stages_array.yaml

Defines the form structure with stages, components, and fields:

- id: basics
  title: "Basics"
  description: "Core building blocks"
  order: 1
  components:
    - id: community_rules
      title: "Community rules" 
      description: "Location and accessibility of guidelines"
      order: 1
      fields:
        - id: communityRulesText
          type: text
          label: "Where does the community keep its rules?"

Template Content: /data/templates/*.yaml

Contains the actual content that populates the form fields when a template is selected.

Current File Organization

/data/
├── stages_array.yaml           # UI structure definition
└── templates/                  # Template content
    ├── shalish-mediation.yaml
    ├── restorative-justice.yaml
    ├── transformative-justice.yaml
    ├── jury-protocol.yaml
    ├── referee-protocol.yaml
    ├── peer-to-peer.yaml
    ├── chosen-facilitator.yaml
    └── facilitation-council.yaml

Available Templates

The system includes 8 complete dispute resolution protocol templates:

1. Shalish Mediation - Traditional Bangladeshi village mediation with modern adaptations
2. Restorative Justice Circle - Community healing and relationship repair
3. Transformative Justice Process - Systemic change and power dynamics focus
4. Community Jury - Formal peer adjudication process
5. Community Referee - Neutral third-party binding decisions
6. Peer-to-Peer Resolution - Direct negotiation approach
7. Chosen Facilitator - Mutually selected facilitation
8. Facilitation Council - Group-based facilitation approach

Markdown Support

Templates support full markdown formatting:

• Bold and italic text
• Links
• Lists and structured content
• Rendered in preview mode and exports

Adding New Features

When extending the system:

1. New Templates: Simply add YAML files to /data/templates/
2. UI Changes: Modify /data/stages_array.yaml
3. Functionality: Update JavaScript in /static/js/builder.js
4. Styling: Update CSS in /static/css/main.css

Deployment Considerations

The current architecture is optimized for static hosting:

• No server-side dependencies beyond Hugo build process
• All data embedded at build time
• Works with any static file server (GitHub Pages, Netlify, etc.)
• No CORS or dynamic loading issues

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