170 lines
5.5 KiB
Markdown
170 lines
5.5 KiB
Markdown
# 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.
|