Skip to main content
Contributions are welcome! Whether you are fixing bugs, adding features, improving documentation, or suggesting ideas, your help makes this project better. This guide covers the contribution workflow, code conventions, and security requirements.

​
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

This project follows specific patterns to maintain consistency: TypeScript
  • Strict type checking enabled, avoid any where possible
  • Use interfaces for data structures, types for unions
  • Prefer const over let, never use var
Architecture
  • 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
Performance
  • Expensive computations should run in the Web Worker
  • Use virtual scrolling for lists with 50+ items
  • Implement circuit breakers for external API calls
No Comments Policy
  • 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

The dashboard handles untrusted data from dozens of external sources. Defense-in-depth measures prevent injection attacks and API abuse.

​
XSS Prevention

All user-visible content is sanitized before DOM insertion: 
escapeHtml(str)  // Encodes & < > " ' as HTML entities
sanitizeUrl(url) // Allows only http/https protocols
This applies to:
  • News headlines and sources (RSS feeds)
  • Search results and highlights
  • Monitor keywords (user input)
  • Map popup content
  • Tension pair labels
The mark element highlighting in search escapes text before wrapping matches, preventing injection via crafted search queries.

​
Proxy Endpoint Validation

Serverless proxy functions validate and clamp all parameters:
EndpointValidation
/api/yahoo-financeSymbol format [A-Za-z0-9.^=-], max 20 chars
/api/coingeckoCoin IDs alphanumeric+hyphen, max 20 IDs
/api/polymarketOrder field allowlist, limit clamped 1-100
This prevents upstream API abuse and rate limit exhaustion from malformed requests.

​
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

DoDon’t
Focus on one feature or fixBundle unrelated changes
Follow existing code patternsIntroduce new frameworks without discussion
Keep changes minimal and targetedRefactor surrounding code unnecessarily
Update README if adding featuresAdd features without documentation
Test edge casesAssume happy path only

​
Types of Contributions

Bug Fixes
  • Found something broken? Fix it and submit a PR
  • Include steps to reproduce in the PR description
New Features
  • New data layers (with public API sources)
  • UI/UX improvements
  • Performance optimizations
  • New signal detection algorithms
Data Sources
  • Additional RSS feeds for news aggregation
  • New geospatial datasets (bases, infrastructure, etc.)
  • Alternative APIs for existing data
Documentation
  • Clarify existing documentation
  • Add examples and use cases
  • Fix typos and improve readability
Security
  • 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
PRs that don’t follow the code style or introduce security issues will be asked to revise.

​
License

By contributing to World Monitor, you agree that your contributions are licensed under AGPL-3.0. See the License page for full terms, commercial licensing, and common scenarios.