Contributing

Documentation Index

Fetch the complete documentation index at: https://worldmonitor.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:
   git clone https://github.com/YOUR_USERNAME/worldmonitor.git
   cd worldmonitor
   
3. Install dependencies:
   npm install
   
4. Create a feature branch:
   git checkout -b feature/your-feature-name
   
5. Start the development server:
   npm run dev
   

​

Code Style & Conventions

• Strict type checking enabled, avoid any where possible
• Use interfaces for data structures, types for unions
• Prefer const over let, never use var

• Services (src/services/) handle data fetching and business logic
• Components (src/components/) handle UI rendering
• Config (src/config/) contains static data and constants
• Utils (src/utils/) contain shared helper functions

• Expensive computations should run in the Web Worker
• Use virtual scrolling for lists with 50+ items
• Implement circuit breakers for external API calls

• Code should be self-documenting through clear naming
• Only add comments for non-obvious algorithms or workarounds
• Never commit commented-out code

​

Security & Input Validation

​

XSS Prevention

escapeHtml(str)  // Encodes & < > " ' as HTML entities
sanitizeUrl(url) // Allows only http/https protocols

• News headlines and sources (RSS feeds)
• Search results and highlights
• Monitor keywords (user input)
• Map popup content
• Tension pair labels

​

Proxy Endpoint Validation

​

Content Security

• URLs are validated via URL() constructor, only http: and https: protocols are permitted
• External links use rel="noopener" to prevent reverse tabnapping
• No inline scripts or eval(), all code is bundled at build time

​

Security Contributions

• Always use escapeHtml() when rendering user-controlled or external data
• Use sanitizeUrl() for any URLs from external sources
• Validate and clamp parameters in API proxy endpoints

​

Submitting a Pull Request

1. Ensure your code builds:
   npm run build
   
2. Test your changes manually in the browser
3. Write a clear commit message:
   Add earthquake magnitude filtering to map layer
   
   - Adds slider control to filter by minimum magnitude
   - Persists preference to localStorage
   - Updates URL state for shareable links
   
4. Push to your fork:
   git push origin feature/your-feature-name
   
5. Open a Pull Request with:
   • A clear title describing the change
   • Description of what the PR does and why
   • Screenshots for UI changes
   • Any breaking changes or migration notes

​

What Makes a Good PR

​

Types of Contributions

• Found something broken? Fix it and submit a PR
• Include steps to reproduce in the PR description

• New data layers (with public API sources)
• UI/UX improvements
• Performance optimizations
• New signal detection algorithms

• Additional RSS feeds for news aggregation
• New geospatial datasets (bases, infrastructure, etc.)
• Alternative APIs for existing data

• Clarify existing documentation
• Add examples and use cases
• Fix typos and improve readability

• Report vulnerabilities via GitHub Issues (non-critical) or email (critical)
• XSS prevention improvements
• Input validation enhancements

​

Review Process

1. Automated checks run on PR submission
2. Maintainer review within a few days
3. Feedback addressed through commits to the same branch
4. Merge once approved

​

License