Contributing

Code style guidelines, pull request process, contribution types, and security practices for the WorldMonitor project.

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:

Endpoint	Validation
/api/yahoo-finance	Symbol format [A-Za-z0-9.^=-], max 20 chars
/api/coingecko	Coin IDs alphanumeric+hyphen, max 20 IDs
/api/polymarket	Order 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

Do	Don’t
Focus on one feature or fix	Bundle unrelated changes
Follow existing code patterns	Introduce new frameworks without discussion
Keep changes minimal and targeted	Refactor surrounding code unnecessarily
Update README if adding features	Add features without documentation
Test edge cases	Assume 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.