builder-prototype/CLAUDE.md

Dispute Protocol Builder

This is a prototype website, built in Hugo, to enable communities to develop customizable protocols for dispute resolution processes. It guides users through an accessible process that provides best practices while allowing for customization.

Project Structure

• Static Site Generator: Hugo
• Main Builder Interface: /themes/dispute-protocol-theme/layouts/_default/builder.html
• JavaScript Files:
  • /static/js/builder.js: Main application logic
• Data Files:
  • /data/stages_array.yaml: Protocol structure (stages, components, and fields)
  • /data/templates/*.yaml: Protocol template definitions with complete content

Content Organization

• Stages and Components: Building blocks of a protocol, defined in /data/stages_array.yaml
• Templates: Complete predefined protocols with content for all fields, defined in /data/templates/*.yaml
• Hugo Data System: Templates are loaded from YAML files via Hugo's data system and made available to JavaScript

Data Model

The application maintains a hierarchical data model:

• Stages → Components → Fields
• Each field is populated with content directly from templates
• Protocol structure: 6 stages with 16 total fields across all components

Protocol Structure (from /data/stages_array.yaml):

1. Basics (3 components): community_rules, shared_values, information_access
2. Process (3 components): process_start, facilitation, ground_rules
3. Assessment (3 components): dispute_assessment, jurisdiction, non_participation
4. Deliberation (3 components): deliberation_process, additional_voices, deliberation_conclusion
5. Resolution (2 components): resolution_process, resolution_failure
6. Appeal (2 components): appeal_criteria, appeal_process

Core Features

1. Black & white UI: Clean, accessible interface with vertical accordion sections
2. Template selection: Users can start with a predefined protocol template
3. Customization: Direct text editing in fields
4. Export options: Markdown, PDF, and JSON formats
5. Import capability: Load previously saved protocols
6. Preview mode: Toggle to see how the final protocol will appear

Template System

Templates provide complete content for dispute resolution protocols:

• Each template has: id, title, description, and nested content data
• Templates define content for all stages and components in YAML format
• Templates are loaded by Hugo from /data/templates/ and injected into JavaScript via builder.html
• The template selector provides one-click application of complete protocols
• Templates are automatically cleared when switching to ensure clean slate

Available Templates:

1. Peer-to-Peer
2. Chosen Facilitator
3. Community Jury
4. Facilitation Council
5. Community Referee
6. Shalish Mediation
7. Restorative Justice
8. Transformative Justice

Recent Improvements

1. Template clearing on switch: Ensures old template content doesn't persist when switching templates
2. Complete template coverage: All templates now have content for all 16 protocol fields
3. Component titles: Simplified all component titles to be more direct and consistent
4. Preview mode: Improved rendering of protocol content with Markdown support
5. Consolidated data structure: Combined stages and components into a unified structure for better maintainability
6. Improved template selection: Updated the template selector from a dropdown to an expandable section with descriptions

Deployment

• Deployable from a self-hosted GitLab server
• All data is maintained in YAML files for stages, components, and templates
• Hugo processes YAML data and makes it available to JavaScript for client-side functionality

Key Files to Modify

Adding or Editing Templates:

• /data/templates/*.yaml: Add, edit or remove protocol templates
• Each template must include all 6 stages with appropriate components and fields

Modifying Protocol Structure:

• /data/stages_array.yaml: Edit stages and components structure in one consolidated file
• Changes here will affect the builder interface and available fields

Customizing Interface:

• /static/js/builder.js: Modify core interface functionality (template application, export, etc.)
• /themes/dispute-protocol-theme/layouts/_default/builder.html: Modify HTML structure
• /static/css/main.css: Adjust styling and responsive behavior

Configuration:

• /config.toml: Hugo site configuration
• /themes/dispute-protocol-theme/layouts/partials/head.html: Script and style includes