154 lines
5.2 KiB
Markdown
154 lines
5.2 KiB
Markdown
# Dispute Protocol Builder Architecture
|
|
|
|
This document explains the architectural decisions made in the Dispute Protocol Builder application.
|
|
|
|
## Current Architecture (2025)
|
|
|
|
The architecture has been completely redesigned to use a YAML-based template system with server-side rendering for maximum reliability and maintainability.
|
|
|
|
### Evolution of Template System
|
|
|
|
**Original Architecture**: Complex JavaScript-based system with modules and template-mappers
|
|
**Previous Architecture**: Direct ES module imports (had cross-platform compatibility issues)
|
|
**Current Architecture**: YAML-based templates with Hugo server-side rendering
|
|
|
|
### Current YAML-Based Template System
|
|
|
|
The new architecture completely eliminates client-side template loading issues:
|
|
|
|
1. **Template Storage**: All templates stored as YAML files in `/data/templates/`
|
|
2. **Server-Side Rendering**: Hugo renders template options directly into HTML at build time
|
|
3. **Data Embedding**: Template data embedded as JSON in the page for immediate JavaScript access
|
|
4. **Event-Based Interaction**: JavaScript adds click handlers to pre-rendered template options
|
|
5. **Automatic Discovery**: New templates automatically appear by simply adding YAML files
|
|
|
|
The template loading process now follows these steps:
|
|
1. During Hugo build, templates are rendered into HTML and data is embedded as JSON
|
|
2. When the page loads, JavaScript parses the embedded template data
|
|
3. Click handlers are attached to pre-rendered template options
|
|
4. When a template is clicked, content is directly applied to form fields
|
|
5. No client-side HTTP requests or ES module imports needed
|
|
|
|
### Template Data Flow
|
|
|
|
```
|
|
YAML files → Hugo build → HTML + embedded JSON → JavaScript parsing → Form population
|
|
(/data/templates/) (build time) (runtime)
|
|
```
|
|
|
|
### Benefits of Current Architecture
|
|
|
|
**Reliability**:
|
|
- No client-side loading issues across different servers/browsers
|
|
- No CORS or ES module compatibility problems
|
|
- Works reliably in production environments
|
|
|
|
**Maintainability**:
|
|
- Templates stored as human-readable YAML
|
|
- Adding templates requires only creating a YAML file
|
|
- No complex JavaScript imports or registrations needed
|
|
- Version control friendly (YAML diffs are readable)
|
|
|
|
**Performance**:
|
|
- Templates loaded instantly at page load (no HTTP requests)
|
|
- Template options rendered at build time
|
|
- Faster user interaction (no loading delays)
|
|
|
|
### Current Template Structure
|
|
|
|
Templates are stored in `/data/templates/` as YAML files:
|
|
|
|
```yaml
|
|
id: "template-id"
|
|
title: "Template Name"
|
|
description: "Brief description"
|
|
|
|
data:
|
|
stages:
|
|
basics:
|
|
community_rules:
|
|
communityRulesText: "Content with **markdown** support"
|
|
# Full protocol structure
|
|
```
|
|
|
|
## Core Data Structure
|
|
|
|
### UI Structure: `/data/stages_array.yaml`
|
|
|
|
Defines the form structure with stages, components, and fields:
|
|
|
|
```yaml
|
|
- id: basics
|
|
title: "Basics"
|
|
description: "Core building blocks"
|
|
order: 1
|
|
components:
|
|
- id: community_rules
|
|
title: "Community rules"
|
|
description: "Location and accessibility of guidelines"
|
|
order: 1
|
|
fields:
|
|
- id: communityRulesText
|
|
type: text
|
|
label: "Where does the community keep its rules?"
|
|
```
|
|
|
|
### Template Content: `/data/templates/*.yaml`
|
|
|
|
Contains the actual content that populates the form fields when a template is selected.
|
|
|
|
## Current File Organization
|
|
|
|
```
|
|
/data/
|
|
├── stages_array.yaml # UI structure definition
|
|
└── templates/ # Template content
|
|
├── shalish-mediation.yaml
|
|
├── restorative-justice.yaml
|
|
├── transformative-justice.yaml
|
|
├── jury-protocol.yaml
|
|
├── referee-protocol.yaml
|
|
├── peer-to-peer.yaml
|
|
├── chosen-facilitator.yaml
|
|
└── facilitation-council.yaml
|
|
```
|
|
|
|
## Available Templates
|
|
|
|
The system includes 8 complete dispute resolution protocol templates:
|
|
|
|
1. **Shalish Mediation** - Traditional Bangladeshi village mediation with modern adaptations
|
|
2. **Restorative Justice Circle** - Community healing and relationship repair
|
|
3. **Transformative Justice Process** - Systemic change and power dynamics focus
|
|
4. **Community Jury** - Formal peer adjudication process
|
|
5. **Community Referee** - Neutral third-party binding decisions
|
|
6. **Peer-to-Peer Resolution** - Direct negotiation approach
|
|
7. **Chosen Facilitator** - Mutually selected facilitation
|
|
8. **Facilitation Council** - Group-based facilitation approach
|
|
|
|
## Markdown Support
|
|
|
|
Templates support full markdown formatting:
|
|
- **Bold** and *italic* text
|
|
- [Links](https://example.com)
|
|
- Lists and structured content
|
|
- Rendered in preview mode and exports
|
|
|
|
## Adding New Features
|
|
|
|
When extending the system:
|
|
|
|
1. **New Templates**: Simply add YAML files to `/data/templates/`
|
|
2. **UI Changes**: Modify `/data/stages_array.yaml`
|
|
3. **Functionality**: Update JavaScript in `/static/js/builder.js`
|
|
4. **Styling**: Update CSS in `/static/css/main.css`
|
|
|
|
## Deployment Considerations
|
|
|
|
The current architecture is optimized for static hosting:
|
|
- No server-side dependencies beyond Hugo build process
|
|
- All data embedded at build time
|
|
- Works with any static file server (GitHub Pages, Netlify, etc.)
|
|
- No CORS or dynamic loading issues
|
|
|
|
For more implementation details, see the README.md file. |