Meet your SGEX Workbench Helper - here to guide you through WHO SMART Guidelines DAK editing!
SGEX is an experimental collaborative project developing a workbench of tools to make it easier and faster to develop high fidelity SMART Guidelines Digital Adaptation Kits (DAKs). Our mission is to empower healthcare organizations worldwide to create and maintain standards-compliant digital health implementations through:
- Collaborative Development: Every contribution matters, whether reporting bugs, testing features, or sharing feedback
- AI-Powered Assistance: Hybrid approach combining human insight with AI coding agents for efficient development
- Community-Driven Evolution: Real-time improvement through collaborative discussion and iterative refinement
- Real-World Impact: Building tools that help healthcare workers worldwide deliver better patient care
Contributing to SGEX is a collaborative journey that combines human creativity with AI assistance:
- 🐛 Start with Feedback: Report bugs, request features, or suggest improvements through our issue tracker
- 🤖 AI-Powered Development: Issues may be assigned to coding agents for initial analysis and implementation
- 🌟 Community Collaboration: The community reviews, tests, and refines changes through collaborative discussion
- 🚀 Real-Time Evolution: The workbench continuously evolves based on actual usage and feedback from healthcare professionals
Every contribution helps improve digital health tools for healthcare workers worldwide. Whether you're reporting a bug, testing a feature, or sharing feedback, you're part of building the future of digital health tooling.
Ready to contribute? Visit our landing page to get started or use the help mascot on any page to quickly report issues.
This repository contains the source code, schemas, and documentation for the SGEX Workbench—a browser-based, standards-compliant collaborative editor for WHO SMART Guidelines Digital Adaptation Kits (DAKs).
The SGEX Workbench provides an intuitive interface for collaborative editing of WHO SMART Guidelines Digital Adaptation Kits (DAKs). Here's what you can expect:
Browse and select from available DAK repositories with enhanced scanning display showing repository details, tags, and metadata.
Access and edit the 8 core DAK components organized according to the WHO SMART Guidelines framework, including Health Interventions, Generic Personas, User Scenarios, Business Processes, Core Data Elements, Decision-Support Logic, Program Indicators, and Requirements.
The SGEX Workbench is a browser-based, static web application for collaborative editing of WHO SMART Guidelines Digital Adaptation Kits (DAKs) content stored in GitHub repositories.
- All UI schemas are rendered using JSON Forms for standards compliance and accessibility.
- All schemas and documentation follow the terminology and branding of WHO SMART Guidelines.
- Node.js: Version 16.x or higher (tested with Node.js 18.x and 20.x)
- npm: Version 8.x or higher (comes with Node.js)
-
Clone the repository
git clone https://github.com/litlfred/sgex.git cd sgex -
Install dependencies
npm install
-
Authentication Setup
SGEX Workbench uses GitHub Personal Access Tokens (PATs) for authentication. No additional setup is required - the application will guide you through creating a PAT when you first sign in.
Note: The app will show helpful step-by-step instructions for creating a Personal Access Token when you try to sign in.
-
Start the development server
npm start
The application will be available at
http://localhost:3000/sgex -
Build for production
npm run build
The build artifacts will be created in the
build/directory. -
Run tests
npm test -
Verify 404.html for GitHub Pages
npm run verify-404
This ensures the 404.html file is properly configured for GitHub Pages SPA routing.
SGEX Workbench includes a comprehensive 404.html file that enables proper Single Page Application (SPA) routing on GitHub Pages. The 404.html file:
- ✅ Handles direct URL navigation (e.g.,
/sgex/dashboard/user/repo) - ✅ Supports multiple deployment scenarios (main branch, feature branches, standalone)
- ✅ Automatically redirects to the correct React Router routes
- ✅ Preserves query parameters and hash fragments
- ✅ Meets GitHub Pages requirements (>512 bytes for IE compatibility)
To verify the 404.html configuration:
npm run build:verify # Build and verify in one command
# OR
npm run verify-404 # Verify existing buildFor detailed implementation information, see docs/404-implementation.md.
SGEX Workbench includes Model Context Protocol (MCP) services that provide structured API access to DAK information:
- Location:
services/dak-faq-mcp/ - URL:
http://127.0.0.1:3001/mcp(local development only) - Purpose: REST API for accessing DAK components and FAQ questions
cd services/dak-faq-mcp
npm install
npm start- FAQ questions catalog and execution
- DAK value sets, decision tables, business processes
- Personas/actors and questionnaires
- Service health checks
- Local Development: Localhost binding (127.0.0.1:8080) for development
- Fly.io Production: Public HTTPS deployment with GitHub OAuth authentication
Complete MCP documentation: public/docs/mcp/
Deployment guide: services/dak-faq-mcp/DEPLOYMENT.md
Security: Local development bypasses authentication. Production deployment requires GitHub OAuth and collaborator access to litlfred/sgex.
- Build the docker image
docker build -t sgex .- Start the docker image
docker run --rm -p 3000:3000 sgexSGEX Workbench uses GitHub Personal Access Tokens (PATs) for secure authentication. This provides a secure authentication method without requiring any backend server setup.
- Users click "Sign in with Personal Access Token"
- The app displays step-by-step instructions for creating a GitHub Personal Access Token
- Users create their PAT with the required permissions and paste it into the app
- The app stores the token securely in the browser and loads the user's repositories
For fine-grained tokens:
- Contents: Read and Write (for editing DAK content)
- Metadata: Read (for repository information)
- Pull requests: Read and Write (for creating pull requests)
For classic tokens:
- repo: Full control of private repositories (for editing DAK content)
- read:org: Read org and team membership (for listing organization repositories)
This authentication method is fully compatible with static deployments and requires no backend server.
sgex/
├── public/ # Static assets
├── src/ # Source code
│ ├── components/ # React components
│ ├── App.js # Main application component
│ └── index.js # Application entry point
├── public/docs/ # Project documentation
├── package.json # Dependencies and scripts
└── README.md # This file
npm start- Runs the app in development modenpm test- Launches the test runner in interactive watch modenpm run build- Builds the app for production (includes TypeScript type checking and schema generation)npm run type-check- Runs TypeScript type checking without compilationnpm run type-check:watch- Runs TypeScript type checking in watch modenpm run generate-schemas- Generates JSON schemas from TypeScript typesnpm run lint- Runs ESLint on all source files (supports JavaScript and TypeScript)npm run lint:a11y- Shows only accessibility (jsx-a11y) warningsnpm run lint:fix- Automatically fixes linting issues where possiblenpm run eject- Note: This is a one-way operation. Don't do this unless you're sure!
SGEX Workbench is currently undergoing a phased migration to TypeScript for improved type safety, better IDE support, and enhanced developer experience. The migration includes:
- Runtime Validation: AJV + TypeScript integration for JSON data validation
- Schema Generation: Automated JSON schema generation from TypeScript types
- Type Safety: Gradual adoption of TypeScript across the codebase
- Documentation: Generated type documentation and schemas
For detailed information about the TypeScript migration, see TYPESCRIPT_MIGRATION.md.
- Core Types: Comprehensive type definitions for GitHub API, DAK structures, and application state
- Runtime Validation: Type-safe JSON validation using generated schemas
- Schema Publishing: Automated schema generation and publishing to
public/docs/schemas/ - Development Tools: TypeScript-aware linting, type checking, and IDE support
// Import types for better development experience
import { GitHubUser, DAKRepository } from './types/core';
import { validateAndCast } from './services/runtimeValidationService';
// Type-safe data validation
const user = validateAndCast<GitHubUser>('GitHubUser', userData);The project uses eslint-plugin-jsx-a11y to enforce accessibility best practices. See docs/accessibility-linting.md for detailed information about accessibility rules and how to fix common issues.
The project includes comprehensive automated security checks that run on every PR build. These checks include:
- NPM Audit - Scans for known vulnerabilities in dependencies
- Outdated Dependencies - Identifies packages needing updates
- ESLint Security Rules - Detects security issues in code
- Security Headers - Verifies security header configuration
- License Compliance - Checks for restrictive licenses
- Secret Scanning - Detects hardcoded secrets
- Framework Compliance - Ensures security best practices
See docs/security-checks.md for detailed information about security checks and how to interpret results.
If you encounter build or installation issues:
- eslint-scope module not found: See TROUBLESHOOTING.md for detailed solutions
- Port 3000 already in use: The development server will automatically try to use an alternative port (3001, 3002, etc.)
- Build issues: Try deleting
node_modules/andpackage-lock.json, then runnpm installagain - Memory issues: If you encounter JavaScript heap out of memory errors, try setting
NODE_OPTIONS=--max-old-space-size=4096before running build commands
For more detailed troubleshooting guidance, see TROUBLESHOOTING.md.
For more information about contributing, see CONTRIBUTING.md.
The SGEX Workbench supports editing of the 9 core Digital Adaptation Kit (DAK) components as defined by the WHO SMART Guidelines framework. These components are organized according to the official DAK authoring sequence:
- Health Interventions and Recommendations - Clinical guidelines and health intervention specifications
- Generic Personas - Standardized user roles and actor definitions
- User Scenarios - Narrative descriptions of user interactions with the system
- Generic Business Processes and Workflows - BPMN workflows and business process definitions
- Core Data Elements - Essential data structures and terminology for clinical data (includes Terminology Services via OCL and Product Master Data via PCMT)
- Decision-Support Logic - DMN decision tables and clinical decision support
- Program Indicators - Performance indicators and measurement definitions
- Functional and Non-Functional Requirements - System requirements and specifications
- Test Scenarios - Feature files and test scenarios for validating the DAK implementation
The SGEX Workbench also supports additional structured knowledge representations including Terminology, FHIR Profiles, FHIR Extensions, FHIR Questionnaires, and Test Data & Examples.
For detailed information about each component, see the DAK Components Documentation.
Note: Scheduling tables are considered a special case of decision tables and are included within the Decision Support Logic component.
For more information on DAK authoring, see the WHO SMART Guidelines IG Starter Kit.
The SGEX Workbench uses a compartmentalized multi-branch GitHub Pages deployment system with separate workflows for branch previews and landing page deployment.
The system consists of two independent workflows:
- Deploy Feature Branch: Automatically deploys each branch to its own preview URL
- Landing Page Deployment: Manually triggered deployment of the main landing page
This separation ensures:
- Branch deployments don't interfere with landing page updates
- Landing page has self-contained assets (no dependencies on branch directories)
- Manual control over landing page updates
- Independent operation of each deployment type
Workflow: Deploy Feature Branch (.github/workflows/branch-deployment.yml)
Automatic Triggers:
- Push to any branch (except
gh-pages) - Pull request events
- Excludes documentation-only changes
Process:
- Builds branch-specific React app with correct base path
- Deploys to branch subdirectory (e.g.,
/main/,/feature-branch/) - Posts deployment URLs to associated pull request comments
- Preserves existing branch directories and landing page
Workflow: Deploy Landing Page (.github/workflows/landing-page-deploy.yml)
Manual Triggers:
- GitHub Actions manual trigger (
workflow_dispatch) - Can be triggered from any branch
- Uses build scripts from the triggering branch
Process:
- Builds self-contained landing page with branch/PR selectors
- Preserves all existing branch deployments
- Deploys landing page to root of GitHub Pages
- Maintains independent assets (CSS, JS, images)
- URL: https://litlfred.github.io/sgex/main/
- Purpose: Primary stable version of the workbench
- Deployment: Automatic via branch preview workflow
- URL Pattern: https://litlfred.github.io/sgex/{branch-name}/
- Purpose: Individual feature development and testing
- Deployment: Automatic on every push to any branch
- Naming: Branch names with slashes converted to dashes (e.g.,
feature/new-editor→feature-new-editor)
- URL: https://litlfred.github.io/sgex/
- Purpose: Browse and access all available branch deployments
- Features: Branch selector, pull request previews, contribution portal
- Deployment: Manual via landing page deployment workflow
Triggered by: Push to any branch, pull request events
- Build → Installs dependencies, builds branch-specific React app
- Deploy → Updates branch subdirectory on GitHub Pages
- Notify → Posts deployment URLs to associated pull request comments
- Complete → Branch preview available within 2-3 minutes
Triggered by: Manual workflow dispatch in GitHub Actions
- Build → Creates self-contained landing page with updated branch listings
- Preserve → Maintains all existing branch directories
- Deploy → Updates root landing page with independent assets
- Complete → Updated landing page available within 2-3 minutes
To manually update the landing page:
- Navigate to GitHub Actions in the repository
- Select "Deploy Landing Page" workflow
- Click "Run workflow"
- Choose source branch (optional - defaults to current branch)
- Run the workflow
The landing page will be updated with latest branch listings, pull request previews, and self-contained assets.
The compartmentalized approach provides several advantages:
- Isolated Updates: Branch deployments don't trigger landing page rebuilds
- Selective Control: Landing page can be updated independently when needed
- Asset Isolation: Landing page has its own CSS, JS, and image assets
- Build Optimization: Landing page build is ~83% smaller (only includes BranchListing component)
- Deployment Flexibility: Landing page can use build scripts from any branch
- Reduced Complexity: Each workflow has a single, clear responsibility
When you push to a branch with an associated pull request:
- Auto-detects PR by branch name or commit SHA
- Posts comment with deployment URLs in PR conversation
- Updates existing comments instead of creating duplicates
- Includes branch preview URL and deployment metadata
- Provides direct access for reviewers to test changes
All project documentation is located in the public/docs/ directory:
- Project Plan - Overall project planning and milestones
- Requirements - Detailed functional and non-functional requirements
- Solution Architecture - Technical architecture and design decisions
- DAK Components - Comprehensive guide to the 8 WHO SMART Guidelines DAK components
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.