worldmonitor/docs/contributing.mdx

---
title: "Contributing"
description: "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:
   ```bash
   git clone https://github.com/YOUR_USERNAME/worldmonitor.git
   cd worldmonitor
   ```
3. **Install dependencies**:
   ```bash
   npm install
   ```
4. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-feature-name
   ```
5. **Start the development server**:
   ```bash
   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:

```typescript
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**:
   ```bash
   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**:
   ```bash
   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

World Monitor is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0-only)](https://www.gnu.org/licenses/agpl-3.0.html).

### What AGPL-3.0 means

AGPL is a strong copyleft license designed for network software. It extends the GPL with one additional requirement: if you run a modified version of World Monitor as a publicly accessible service, you must make your source code available to users of that service.

| You can | You must | You cannot |
|---------|----------|------------|
| View, study, and learn from the source code | Distribute source code with any binary distribution | Use World Monitor commercially without a commercial license |
| Modify and create derivative works for personal/research use | License derivative works under AGPL-3.0 | Sublicense under a different license |
| Run a personal instance for non-commercial use | State changes you made to the code | Hold the author liable |
| Contribute improvements back to the project | Provide source access to users of any public-facing modified deployment | Use the project's trademarks without permission |

### Commercial use requires a separate license

**Any commercial use of World Monitor requires a commercial license from the maintainer.** This includes but is not limited to:

- Running World Monitor (or a modified version) as a paid product or service
- Embedding World Monitor code, components, or data pipelines into a commercial product
- Offering World Monitor's capabilities as part of a consulting, SaaS, or managed service
- Using World Monitor internally at a for-profit company to generate revenue or competitive advantage

The AGPL-3.0 license governs non-commercial, personal, educational, and research use. If your use case involves any form of commercial activity, contact the maintainer to obtain a commercial license.

### Common scenarios

**Personal use or research**: Free to use, modify, and self-host. No restrictions beyond AGPL compliance.

**Self-hosting for a non-profit or educational institution**: Permitted under AGPL. If you modify the code and make it publicly accessible, you must share your modifications.

**Running a modified public instance (non-commercial)**: You must make your modified source code available to users who interact with your deployment. The simplest way is to publish your fork on GitHub and link to it from your instance.

**Using World Monitor's public API in your own tool**: If your tool calls World Monitor's public API and displays the results, your tool is not a derivative work. No AGPL obligations apply. However, if your tool is commercial, you must comply with the API terms of service.

**Contributing a pull request**: By submitting a PR, you agree that your contribution is licensed under AGPL-3.0, consistent with the rest of the project.

**Commercial use (any of the above in a for-profit context)**: Requires a separate commercial license. Contact the maintainer at the [GitHub repository](https://github.com/koala73/worldmonitor).

### Why AGPL + Commercial License

World Monitor aggregates publicly available intelligence data and makes it accessible to everyone. The dual-license model (AGPL for open use, commercial license for business use) ensures that:

1. **The community benefits**: Individual researchers, journalists, students, and open-source contributors can freely use and improve the platform.
2. **Commercial use is sustainable**: Companies that derive commercial value from World Monitor contribute back through licensing fees, which fund continued development.
3. **The project stays open**: AGPL prevents a scenario where a commercial entity takes the open-source code, adds proprietary features, and competes with the project without contributing back.