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
• 8 complete protocol templates for different facilitation styles
• YAML-based template system for easy content management
• Server-side template rendering for reliable cross-platform compatibility
• Export protocols as Markdown, PDF, or JSON
• Import previously created protocols (JSON format)
• Markdown support for rich text formatting in preview mode and exports
• 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 builder-prototype
hugo server -D

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

Customizing the Dispute Protocol

Adding or Modifying Stages and Components

The UI structure is defined in data/stages_array.yaml, which contains all stages, components, and fields in a consolidated format:

- id: new-stage
  title: "New Stage Name"
  description: "Description of this stage"
  order: 7  # This determines the order in which stages appear
  components:
    - id: new-component
      title: "New Component Title"
      description: "Description of what this component addresses"
      order: 1
      fields:
        - id: newComponentField
          type: text
          label: "Field Label"
          placeholder: "Placeholder text..."
          required: true

Using Protocol Templates

The application includes 8 complete protocol templates that pre-fill all components with consistent content:

1. Shalish Mediation: Traditional mediation process from Bangladesh with modern adaptations
2. Restorative Justice Circle: Community-based approach focusing on healing relationships
3. Transformative Justice Process: Addresses systemic issues and power dynamics
4. Community Jury: Formal adjudication process with community jurors
5. Community Referee: Neutral third party makes binding decisions
6. Peer-to-Peer Resolution: Direct negotiation with minimal third-party intervention
7. Chosen Facilitator: Participants mutually select a facilitator
8. Facilitation Council: Group of trained facilitators support resolution

Users can select a template from the Templates section to automatically populate all fields. Templates support full markdown formatting including links, bold text, and lists.

Adding New Protocol Templates

To add a new protocol template:

1. Create a new YAML file in the data/templates/ directory (e.g., my-new-template.yaml)
2. Define your template with this structure:

id: "my-new-template"
title: "My New Template"
description: "Brief description of this template approach"

data:
  stages:
    basics:
      community_rules:
        communityRulesText: "Your content here with **markdown** support and [links](https://example.com)"
      shared_values:
        sharedValuesText: "Content for shared values..."
    # Continue with all stages and components

3. The template will automatically appear in the Templates section - no code changes needed!

Templates are rendered server-side by Hugo and embedded directly in the HTML, ensuring reliable loading across all deployment environments.

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 with YAML data files
• Server-side template rendering for cross-platform compatibility
• Modern JavaScript for form interactions and export functionality
• YAML-based template system for easy content management
• jsPDF for PDF generation
• Marked.js for Markdown rendering in preview mode and exports

License

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