Skip to content

CONTRIBUTING

Jump to bottom
John Williams edited this page Mar 9, 2026 · 1 revision

Contributing to ARGUS

Thank you for helping make the internet more authentic.

What We Need Most

  • New platform connectors — TikTok, Nextdoor, Mastodon, Bluesky
  • Detection model improvements — better GAN detection, voice cloning, video deepfake
  • False positive reduction — help tune weights and thresholds
  • Browser extension platform support — more DOM selectors for existing platforms
  • Documentation — guides, tutorials, translations

Architecture Philosophy

ARGUS follows the Agent-Reach scaffolding model. Every component is a pluggable, replaceable module. Adding a new platform or swapping a detection model should require changing one file, not the whole system.

engines/
├── image_engine.py    ← swap: HuggingFace → DeepSafe → Hive
├── audio_engine.py    ← swap: Resemblyzer → pyannote → custom
├── text_engine.py     ← swap: GPTZero → HuggingFace → custom
└── profile_engine.py  ← behavioral signal scoring

Getting Started

Prerequisites

  • Node.js 20+
  • Wrangler CLI (npm install -g wrangler)
  • A Cloudflare account (free tier is sufficient for dev)

Local Development

git clone https://github.com/itallstartedwithaidea/argus
cd argus
npm install

# Set up local D1
wrangler d1 create argus-dev
wrangler d1 execute argus-dev --file=./schema/d1_schema.sql --local

# Create .dev.vars (local secrets)
cp .dev.vars.example .dev.vars
# Fill in your API keys

# Run Worker locally
wrangler dev workers/api/index.js --local

# Run Pages locally (separate terminal)
cd pages && npm install && npm run dev

Adding a New Detection Engine

  1. Create workers/engines/[name]_engine.js
  2. Export a function: async function run(profileData, env) → { score, reason, signals[] }
  3. Register it in workers/pipeline/analyze.js
  4. Add weight to aggregateScore() function
  5. Add tests in tests/engines/[name].test.js

Adding a New Platform Connector

  1. Create workers/ingestion/[platform].js
  2. Export: async function fetchProfile(url, env) → ProfileData
  3. Add hostname detection to workers/lib/utils.js detectPlatform()
  4. Add DOM selectors to extension/content_script.js PLATFORM_SELECTORS
  5. Document in wiki/Platform-Connectors.md

Pull Request Process

  1. Fork the repo
  2. Create a feature branch: git checkout -b feature/tiktok-connector
  3. Write tests for your changes
  4. Ensure npm test passes
  5. Update relevant wiki documentation
  6. Submit PR with a clear description

Code Standards

  • Cloudflare Workers environment — no Node.js-specific APIs
  • No external npm dependencies in Workers (use native fetch, crypto, etc.)
  • All detection engines must return { score: 0-100, reason: string, signals: [] }
  • Score semantics: lower = more suspicious (0 = definitely fake, 100 = definitely real)
  • Never use the word "fake" in user-facing strings — use "flagged", "high risk", "suspicious"

Legal Considerations

All contributions must follow the legal framing established in the project:

  • Frame all analysis as algorithmic opinion, never as factual verdicts
  • Never recommend specific actions against identified accounts
  • Ensure dispute mechanisms remain functional for any new features
  • Do not build features that would identify individuals without their knowledge in ways that exceed what the platform itself makes public

Dispute This Project's Analysis

ARGUS operates as it instructs — if you believe a finding in our codebase is wrong, open an issue.

Code of Conduct

This project is built to protect people from coordinated inauthentic behavior. We do not tolerate:

  • Using this tool to target individuals maliciously
  • Submitting bad-faith profiles to harm real people
  • Weaponizing the dispute system to suppress legitimate analysis

Violations result in permanent bans from the project.

Clone this wiki locally