Contributing

darkreach is open source under the MIT license. Contributions are welcome — whether it is a bug fix, new prime form, performance improvement, or documentation update.

Development Setup

bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/darkreach.git
cd darkreach

# Install dependencies
# macOS: brew install gmp
# Linux: sudo apt install build-essential libgmp-dev m4

# Build and test
cargo build
cargo test

Frontend development

bash
# Dashboard (app.darkreach.ai)
cd frontend && npm install && npm run dev

# Website (darkreach.ai)
cd website && npm install && npm run dev

Workflow

  1. Fork the repository on GitHub
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Make your changes with tests
  4. Run the full test suite: cargo test
  5. Run clippy: cargo clippy -- -D warnings
  6. Format: cargo fmt
  7. Open a pull request against master

Branch naming: feat/, fix/, chore/, docs/, deploy/. PRs use squash-and-merge by default.

Code Style

  • Rust: Follow rustfmt defaults. No unsafe in the main crate (except the macOS QoS syscall).
  • Comments: This codebase is a teaching tool for computational number theory. Document algorithms at an academic level — cite theorems, link OEIS sequences, reference papers.
  • Engine files: ~30-40% comments. Server: ~20-30%. Frontend: ~15-25%.
  • All output goes to stderr (eprintln!). Results are logged to PostgreSQL.

Testing

bash
# Run all unit tests (1000+ passing)
cargo test

# Integration tests
cargo test --test db_integration
cargo test --test api_integration
cargo test --test cli_tests
cargo test --test property_tests
cargo test --test security_tests

# Benchmarks
cargo bench

# Run with small ranges to verify quickly
cargo run -- factorial --start 1 --end 100
cargo run -- kbn --k 3 --base 2 --min-n 1 --max-n 1000
cargo run -- palindromic --base 10 --min-digits 1 --max-digits 9

# Frontend
cd frontend && npm test           # Vitest unit tests
cd frontend && npm run test:e2e   # Playwright E2E tests

Adding a New Prime Form

To add a new search form (e.g., mega-primes):

  1. Create src/mega_primes.rs following the sieve → filter → test → prove → report pipeline
  2. Add the module to src/lib.rs
  3. Add a CLI subcommand in src/main.rs and dispatch in src/cli.rs
  4. Add a checkpoint variant in src/checkpoint.rs
  5. Add search manager support in src/search_manager.rs
  6. Add deploy support in src/deploy.rs
  7. Add the form to website/src/lib/prime-forms.ts
  8. Write tests covering known primes and edge cases

Adding an API Endpoint

  1. Create handler in appropriate src/dashboard/routes_*.rs file (or create a new route module)
  2. Register the route in src/dashboard/mod.rs
  3. Add DB query methods in src/db/*.rs submodule
  4. Add migration if new tables needed (supabase/migrations/)

Project Structure

src/
├── main.rs              # CLI routing (clap)
├── cli.rs               # CLI execution, search dispatch
├── lib.rs               # Module re-exports, utilities
│
├── [12 Search Forms]
├── factorial.rs         # n! ± 1
├── palindromic.rs       # Palindromic primes
├── kbn.rs               # k·b^n ± 1
├── ... (9 more form modules)
│
├── [Core Primitives]
├── sieve.rs             # Sieve, Montgomery, BitSieve, wheel
├── proof.rs             # Pocklington, Morrison, BLS proofs
├── verify.rs            # 3-tier verification pipeline
├── certificate.rs       # Primality certificates
├── p1.rs                # Pollard P-1 factoring
│
├── [External Tools]
├── pfgw.rs              # PFGW subprocess
├── prst.rs              # PRST subprocess
├── gwnum.rs             # GWNUM FFI (feature-gated)
│
├── [AI & Strategy]
├── ai_engine.rs         # OODA decision loop
├── agent.rs             # AI agent infrastructure
├── classify.rs          # Result classification
│
├── [Server]
├── dashboard/           # Axum web server (15 route modules)
│   ├── mod.rs           # Router, AppState, middleware
│   ├── websocket.rs     # WebSocket (2s push)
│   ├── routes_*.rs      # 13 route modules
│   └── ...
├── db/                  # PostgreSQL via sqlx (13 submodules)
│   ├── mod.rs           # Database struct, pool, types
│   ├── primes.rs        # Prime CRUD
│   ├── workers.rs       # Worker management
│   ├── jobs.rs          # Search jobs, work blocks
│   ├── agents.rs        # Agent tasks, budgets
│   ├── projects.rs      # Project campaigns
│   ├── operators.rs     # Operator accounts
│   └── ...
├── project/             # Campaign management
│   ├── config.rs        # TOML configuration
│   ├── cost.rs          # Power-law cost model
│   ├── orchestration.rs # Phase state machine
│   └── ...
│
├── [Infrastructure]
├── checkpoint.rs        # JSON checkpoint save/load
├── search_manager.rs    # Work distribution
├── fleet.rs             # In-memory worker registry
├── pg_worker.rs         # PostgreSQL work claiming
├── worker_client.rs     # Worker HTTP client
├── operator.rs          # Operator management
├── events.rs            # Event bus
├── metrics.rs           # System metrics
├── prom_metrics.rs      # Prometheus export
├── deploy.rs            # SSH deployment
└── progress.rs          # Atomic counters

frontend/                # Dashboard (app.darkreach.ai)
├── src/app/             # 17 Next.js pages
├── src/components/      # 50+ React components
├── src/hooks/           # 18 custom hooks
└── public/              # PWA assets, icons

website/                 # Public site (darkreach.ai)
├── src/app/             # 14 pages (landing, docs, blog, etc.)
├── src/components/      # UI components + Three.js
└── src/lib/             # Data files and utilities

Questions?

Open an issue on GitHub or join the Discord for help with onboarding.