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](https://gohugo.io/installation/) installed
2. Clone this repository
3. Run the local development server:

```bash
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.

```yaml
- 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`:

```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.

```yaml
- 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.

```javascript
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:

```javascript
{
  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:

```bash
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:

```nginx
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:

```apache
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.