dispute-protocol/builder-prototype
2
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Improvements in template handling and loading

Browse Source
This commit is contained in:
Nathan Schneider
2025-07-22 12:17:25 -06:00
parent 3ef15444fe
commit 847b603734
59 changed files with 1070 additions and 2153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
ARCHITECTURE.md
View File

@@ -2,127 +2,153 @@
This document explains the architectural decisions made in the Dispute Protocol Builder application.
## Latest Architecture Update
## Current Architecture (2025)
The architecture has been significantly simplified to make it more maintainable and easier to extend.
The architecture has been completely redesigned to use a YAML-based template system with server-side rendering for maximum reliability and maintainability.
### Template System
### Evolution of Template System
The original architecture had a complex system of modules and templates:
**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
1. Templates contained raw content
2. The template-mapper tried to match content to existing modules
3. If no match was found, it created custom modules
4. The builder would load templates and convert them to use module references
### Current YAML-Based Template System
This approach became unnecessarily complex and had several drawbacks:
- Adding new templates required modifying multiple files
- The module matching logic was brittle and hard to maintain
- Many modules weren't actually reused across templates
The new architecture completely eliminates client-side template loading issues:
### New Simplified Architecture
The new architecture uses a direct template system:
1. Each template is stored in its own file in `/static/js/templates/`
2. Templates contain the full content for all stages and components
3. The index.js file imports and exports all templates
4. Templates are loaded dynamically in builder.js using ES Modules
5. Stages and components are now consolidated in a single YAML file
6. Template selection is now an expandable section rather than a dropdown
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. When the page loads, the `fetchTemplates()` function is called
2. The function dynamically imports the templates index file using ES modules
3. The templates are stored in memory and used to populate the template options
4. When a template is selected, the content is directly applied to the form fields
5. The template cards show both the title and description for better user understanding
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
Benefits of this approach:
- Adding a new template is as simple as creating a new file and registering it in index.js
- No complex module matching logic or multiple data sources
- Clear 1:1 relationship between files and templates
- Easier to understand and maintain
- Improved error handling and debugging capabilities
- Single source of truth for template data
- Consolidated data structure improves maintainability
- Enhanced template selection UI provides more context for users
### Template Data Flow
### Template Loading Implementation
The core of the template loading is implemented in `builder.js`:
```javascript
// Function to fetch templates - simplified approach
function fetchTemplates() {
console.log('Fetching templates...');
// Load all templates at startup
try {
import('/js/templates/index.js')
.then(module => {
templates = module.default;
console.log('Templates loaded successfully:', templates.length, 'templates found');
// Populate the template selector
populateTemplateSelector(templates);
// Add template selection event handler
if (protocolTemplateSelect) {
protocolTemplateSelect.addEventListener('change', handleTemplateSelection);
console.log('Template selector event handler attached');
} else {
console.error('Template select element not found');
}
})
.catch(error => {
console.error('Error importing templates:', error);
});
} catch (e) {
console.error('Error loading templates:', e);
}
}
```
YAML files → Hugo build → HTML + embedded JSON → JavaScript parsing → Form population
(/data/templates/) (build time) (runtime)
```
### Simplified Component Names
### Benefits of Current Architecture
All component titles have been simplified to be more direct and consistent:
- First-word capitalization only
- Short, descriptive phrases (2-3 words) instead of questions
- Example: "Process initiation" instead of "How does the process begin?"
**Reliability**:
- No client-side loading issues across different servers/browsers
- No CORS or ES module compatibility problems
- Works reliably in production environments
### Removed Components
**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)
The following components have been removed:
- YAML-based template configuration - No longer needed as templates are defined directly in JS
- Complex module mapper logic - Templates now contain direct content
- Module selection UI - Removed from the interface
**Performance**:
- Templates loaded instantly at page load (no HTTP requests)
- Template options rendered at build time
- Faster user interaction (no loading delays)
### Migration Process
### Current Template Structure
To migrate a template from the old system to the new one:
1. Create a new file in `/static/js/templates/`
2. Copy the raw template structure from templates.js
3. Register the template in index.js
Templates are stored in `/data/templates/` as YAML files:
### Future Considerations
```yaml
id: "template-id"
title: "Template Name"
description: "Brief description"
If common content needs to be shared between templates in the future, standard JavaScript functions or objects can be used to generate that content without the overhead of the complex module system.
data:
stages:
basics:
community_rules:
communityRulesText: "Content with **markdown** support"
# Full protocol structure
```
## Core Components
## Core Data Structure
The application is still built on the following core components:
### UI Structure: `/data/stages_array.yaml`
1. **Stage and Component Structure** - Now defined in a single consolidated YAML file (`data/stages_array.yaml`)
2. **Templates** - Complete predefined protocols stored in individual files
3. **Builder Interface** - Interactive UI for customizing protocols, with improved template selection
4. **Export System** - Tools to export protocols in various formats
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 adding new features:
1. Keep the one-template-per-file architecture
2. Focus on the user experience of building and customizing protocols
3. Test thoroughly with multiple templates
When extending the system:
For more details on implementation, see the README.md file.
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.