Initial commit
This commit is contained in:
Nathan Schneider
196
README.md
Normal file
196
README.md
Normal file
@ -0,0 +1,196 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user