185 lines
5.3 KiB
Markdown
185 lines
5.3 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
|
|
- Complete protocol templates for different facilitation styles
|
|
- Simple template system with direct content application
|
|
- Export protocols as Markdown, PDF, or JSON
|
|
- Import previously created protocols (JSON format)
|
|
- Markdown support for rich text formatting
|
|
- 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
|
|
```
|
|
|
|
### Using Protocol Templates
|
|
|
|
The application includes complete protocol templates that pre-fill all components with consistent content. Several templates are provided:
|
|
|
|
1. **Shalish Mediation**: A process based on the traditional shalish process for village-level mediation in Bangladesh, with modernizing improvements.
|
|
|
|
2. **Restorative Justice**: A collaborative process that focuses on healing relationships and repairing harm rather than punitive measures.
|
|
|
|
3. **Transformative Justice**: A process that addresses immediate harm while working to transform the conditions that allowed harm to occur.
|
|
|
|
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:
|
|
|
|
1. Create a new JavaScript file in the `static/js/templates/` directory
|
|
2. Define your template with the following structure:
|
|
|
|
```javascript
|
|
const newTemplate = {
|
|
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
|
|
}
|
|
}
|
|
};
|
|
|
|
export default newTemplate;
|
|
```
|
|
|
|
3. Register the template in `static/js/templates/index.js`:
|
|
|
|
```javascript
|
|
import newTemplate from './template-id.js';
|
|
|
|
const templates = [
|
|
// existing templates...
|
|
newTemplate,
|
|
];
|
|
|
|
export default templates;
|
|
```
|
|
|
|
The builder will automatically load all templates registered in the index.js file at startup.
|
|
|
|
## 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
|
|
- Modern JavaScript (ES Modules) for template management
|
|
- Modular template architecture with simplified importing
|
|
- jsPDF for PDF generation
|
|
- Marked.js for Markdown rendering
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details.
|