builder-prototype/README.md

Community Dispute Protocol Builder

A Hugo-based web application that helps communities create structured processes for resolving conflicts and disputes.

Created as a prototype by Nathan Schneider with Claude Code.

Features

• Interactive protocol builder with multi-stage process
• Pre-defined modules for common dispute resolution approaches
• Complete protocol templates for different facilitation styles
• Export protocols as Markdown, PDF, or JSON
• Import previously created protocols (JSON format)
• Responsive design for desktop and mobile

Setup and Installation

1. Make sure you have Hugo installed
2. Clone this repository
3. Run the local development server:

cd dispute-protocol
hugo server -D

4. Access the site at http://localhost:1313/

Customizing the Dispute Protocol

Adding or Modifying Stages

Edit the file data/stages/stages.yaml to modify the stages of the dispute resolution process.

- id: new-stage
  title: New Stage Name
  description: Description of this stage
  order: 7  # This determines the order in which stages appear

Adding or Modifying Components

Components are grouped by stage. Create or edit files in the data/components/ directory, naming the file after the stage ID.

For example, to add components to a stage with ID "new-stage", create data/components/new-stage.yaml:

- id: new-component
  title: New Component Title
  description: Description of what this component addresses
  stageId: new-stage
  order: 1
  fields:
    - id: newComponentField
      type: text
      label: Field Label
      placeholder: Placeholder text...
      required: true

Adding Pre-defined Modules

Modules provide pre-written content that users can select for specific fields. There are two places where modules are defined:

1. YAML Definition (source of truth): Create or edit files in the data/modules/ directory.

- id: new-module
  title: New Module Title
  componentId: new-component
  fieldId: newComponentField
  content: |
    This is the pre-defined content that will be inserted when
    the user selects this module. It can include multiple lines.

2. JavaScript Implementation: The frontend uses modules defined in static/js/data/modules.js. When adding new modules to the YAML files, you should also add them to this JavaScript file to make them available in the builder interface.

const moduleData = {
  module_category: [
    {
      id: "new-module",
      title: "New Module Title",
      componentId: "new-component",
      fieldId: "newComponentField",
      content: `This is the pre-defined content that will be inserted when
the user selects this module. It can include multiple lines.`
    }
  ]
};

Important: Make sure the componentId and fieldId values match exactly with the component and field IDs defined in the data/components/ directory.

Using Protocol Templates

The application includes complete protocol templates that pre-fill all components with consistent content. Three templates are provided:

1. Peer-to-Peer Protocol: A self-facilitated process where participants work together directly to resolve disputes without a formal facilitator.

2. Chosen Facilitator Protocol: A process where participants mutually select a facilitator who may not have specialized skills but can help guide the discussion.

3. Facilitation Council Protocol: A structured process with a trained council of facilitators who manage the dispute resolution process.

Users can select a template from the dropdown at the top of the builder page to automatically populate all fields. They can then customize the content as needed for their community's specific requirements.

Adding New Protocol Templates

To add a new protocol template, edit the file static/js/data/templates.js. Each template follows this structure:

{
  id: "template-id",
  title: "Template Name",
  description: "Brief description of this template approach",
  data: {
    stages: {
      // Full protocol data structure with content for all stages and components
    }
  }
}

Deployment

Building for Production

To build the site for production:

hugo --minify

The generated site will be in the public directory, which you can deploy to any static hosting service.

Deploying from a Self-Hosted GitLab Server

This project includes GitLab CI/CD configuration for easy deployment. The included .gitlab-ci.yml file supports two deployment options:

1. GitLab Pages - Automatically deployed when you push to the master branch
2. Custom Server Deployment - Deploy to your own server using rsync

Setting Up Custom Server Deployment

1. In your GitLab repository, go to Settings > CI/CD > Variables

2. Add the following variables:

   • SSH_PRIVATE_KEY: Your private SSH key for the deployment server
   • SSH_KNOWN_HOSTS: Output of ssh-keyscan your-server.com
   • SSH_USER: Username on your deployment server
   • SSH_HOST: Hostname or IP of your deployment server
   • DEPLOY_PATH: Path on your server where the site should be deployed

3. Uncomment the deploy job in .gitlab-ci.yml

4. Update the url parameter in the environment section with your actual domain

5. Push your changes to the master branch to trigger the deployment

Web Server Configuration

For Nginx, use a configuration similar to this:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        root /path/to/deployment;
        index index.html;
        try_files $uri $uri/ =404;
    }
}

For Apache, create a .htaccess file in your deployment directory:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /index.html [L]

Technologies Used

• Hugo static site generator
• JavaScript for interactive features
• jsPDF for PDF generation

License

This project is licensed under the MIT License - see the LICENSE file for details.