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

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

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

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

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