Architecture

darkreach is a five-layer system: a high-performance Rust engine for number theory computation, an AI engine for autonomous strategy, an Axum server for coordination, a PostgreSQL database for persistence, and two Next.js frontends for public and operational interfaces.

System Overview

┌─────────────────────────────────────────────────────────┐
│                    darkreach.ai                          │
│               (Next.js static export)                   │
│        Landing · Docs · Status · Blog · Leaderboard      │
└─────────────────────────────────────────────────────────┘

┌────────────────────┐      ┌────────────────────────────────┐
│  app.darkreach.ai  │─────▶│      api.darkreach.ai          │
│  (Next.js + SPA)   │ WS   │    (Axum web server)           │
│                    │◀─────│                                │
│  Browse · Searches │      │  REST API (15 route modules)   │
│  Network · Agents  │      │  WebSocket (2s push)           │
│  Projects · Logs   │      │  AI Engine (OODA loop)         │
│  Strategy · Verify │      │  Project Orchestrator          │
└────────────────────┘      └───────────┬────────────────────┘
                                        │
                             ┌──────────▼─────────────────┐
                             │       PostgreSQL            │
                             │   (Supabase / self-hosted)  │
                             │                             │
                             │  primes · workers · jobs    │
                             │  projects · agents · ai     │
                             │  operators · releases       │
                             │  24 migrations              │
                             └──────────┬─────────────────┘
                                        │
           ┌────────────────────────────┼─────────────────────────┐
           │                            │                         │
  ┌────────▼────────┐      ┌────────────▼──────┐     ┌───────────▼────────┐
  │  Operator Alice  │      │  Operator Bob     │     │  Operator Charlie  │
  │  ┌─────┐┌─────┐ │      │  ┌─────┐┌─────┐  │     │  ┌─────┐           │
  │  │Node1││Node2│ │      │  │Node1││Node2│  │     │  │Node1│           │
  │  │8cor ││8cor │ │      │  │16cor││4cor │  │     │  │32cor│           │
  │  └─────┘└─────┘ │      │  └─────┘└─────┘  │     │  └─────┘           │
  └──────────────────┘      └──────────────────┘     └────────────────────┘

Engine

The engine is the core Rust library implementing 12 prime search algorithms. Each form follows the same pipeline:

Sieve — Eliminate composites using form-specific sieves (wheel factorization, BSGS, Montgomery multiplication)
Filter — Deep composite elimination via adaptive Pollard P-1 (Stage 1 + Stage 2)
Test — Miller-Rabin pre-screening (25 rounds), then specialized tests (Proth, LLR, Pepin). Frobenius RQFT for >10K-bit candidates
Prove — Generate deterministic primality certificates (Pocklington, Morrison, BLS, Proth, LLR)
Report — Log results to PostgreSQL with certificate data, update project progress

Key engine modules

Module	Purpose
`src/sieve.rs`	Eratosthenes sieve, Montgomery multiplication, BitSieve (packed u64), wheel factorization, BSGS
`src/lib.rs`	Trial division, MR pre-screening, Frobenius RQFT, small primes table
`src/proof.rs`	Pocklington (N-1), Morrison (N+1), BLS deterministic proofs
`src/verify.rs`	3-tier verification pipeline (deterministic → BPSW+MR → PFGW)
`src/p1.rs`	Pollard P-1 factoring with adaptive B1/B2 tuning
`src/certificate.rs`	PrimalityCertificate enum (7 variants) for witness serialization
`src/pfgw.rs`	PFGW subprocess integration (50-100x acceleration)
`src/prst.rs`	PRST subprocess for k*b^n forms

12 search form modules

Module	Form
`factorial.rs`	n! ± 1
`primorial.rs`	p# ± 1
`kbn.rs`	k·b^n ± 1 (Proth/Riesel)
`cullen_woodall.rs`	n·2^n ± 1
`gen_fermat.rs`	b^(2^n) + 1
`wagstaff.rs`	(2^p + 1) / 3
`carol_kynea.rs`	(2^n ± 1)² − 2
`twin.rs`	Twin primes (p, p+2)
`sophie_germain.rs`	Sophie Germain (p, 2p+1)
`palindromic.rs`	Palindromic primes
`near_repdigit.rs`	Near-repdigit palindromic
`repunit.rs`	R(b,n) = (b^n − 1) / (b − 1)

AI Engine

The AI engine is an autonomous decision system that replaces manual tuning with a unified OODA (Observe → Orient → Decide → Act) loop running every 30 seconds:

WorldSnapshot — Consistent view of fleet, costs, records (~50ms via parallel DB queries)
7-component scoring — record_gap, yield_rate, cost_efficiency, opportunity_density, fleet_fit, momentum, competition
Online learning — Weights updated via gradient descent on actual outcomes
Power-law cost model — OLS-fitted coefficients for compute time prediction
Drift detection — Automatic response to fleet changes, stalls, and discoveries

Server

The server is a modular Axum web application with 15 route modules:

Dashboard modules (`src/dashboard/`)

Module	Path	Purpose
`routes_health.rs`	/api/health	Health check, readiness probes
`routes_status.rs`	/api/status	Coordinator status summary
`routes_workers.rs`	/api/workers	Worker/node registration, heartbeat, pruning
`routes_operator.rs`	/api/v1/operators, /api/v1/nodes	Operator accounts, node management
`routes_fleet.rs`	/api/fleet	Fleet overview (all nodes + searches)
`routes_jobs.rs`	/api/search_jobs	Job CRUD, work blocks, claiming
`routes_searches.rs`	/api/searches	Search management
`routes_agents.rs`	/api/agents	AI agent tasks, budgets, memory, schedules
`routes_projects.rs`	/api/projects	Multi-phase project campaigns
`routes_verify.rs`	/api/verify	Prime re-verification
`routes_docs.rs`	/api/docs	Documentation search and serving
`routes_releases.rs`	/api/releases	Worker release channels, canary rollout
`routes_observability.rs`	/api/observability	Metrics, logs, performance charts
`routes_notifications.rs`	/api/notifications	Push notification management
`websocket.rs`	/ws	Real-time push (2s interval)

Database modules (`src/db/`)

PostgreSQL access is split into 13 domain-specific submodules:

Module	Tables
`primes.rs`	primes (insert, query, filter, verify)
`workers.rs`	workers (heartbeat, registration, pruning)
`jobs.rs`	search_jobs, work_blocks (lifecycle, claiming)
`agents.rs`	agent_tasks, agent_events, agent_budgets
`memory.rs`	agent_memory (key-value store)
`projects.rs`	projects, project_phases, project_events
`operators.rs`	operators, operator_nodes
`records.rs`	world_records (t5k.org tracking)
`calibrations.rs`	cost_calibrations (power-law coefficients)
`releases.rs`	worker_releases, rollout_events
`observability.rs`	metrics, worker_rates, logs
`roles.rs`	agent_roles (configuration)
`schedules.rs`	agent_schedules (automation)

Project orchestration (`src/project/`)

Campaign management is a separate module with its own submodules:

config.rs — TOML configuration parsing and validation
cost.rs — Power-law cost estimation model
orchestration.rs — Phase state machine, 30s tick loop
records.rs — World record tracking via t5k.org scraping
types.rs — Database row types for projects, phases, events

Frontends

Two separate Next.js 16 applications:

Website (website/) — Public-facing site at darkreach.ai. Landing page, documentation, blog, status, and leaderboard. Static export deployed to Vercel.
Dashboard (frontend/) — Operational dashboard at app.darkreach.ai. 17 pages including prime browser, search management, network monitoring, AI agent control, project campaigns, performance metrics, and system logs. React 19 + Tailwind 4 + shadcn/ui + Recharts. Supabase Auth for login. WebSocket for real-time coordination. PWA-enabled with offline support.

Data Flow

AI engine scores forms and decides which searches to run
Coordinator generates work blocks and inserts them into PostgreSQL
Nodes claim blocks using FOR UPDATE SKIP LOCKED
Nodes run the sieve → filter → test → prove pipeline
Results (primes + certificates) are written back to PostgreSQL
AI engine observes outcomes and updates scoring weights
Project orchestrator tracks phase progress and manages budgets
Dashboard queries PostgreSQL via Supabase for display
WebSocket pushes real-time notifications for new primes and fleet status

Deployment

The production deployment runs on Hetzner Cloud:

Coordinator — CX22 instance running the Axum server, AI engine, and project orchestrator
Nodes — CCX23 instances (4+ cores) running darkreach in worker mode
Database — Supabase-hosted PostgreSQL (24 migrations)
Website — Vercel static deployment
Dashboard — Static export served by the coordinator
Monitoring — Prometheus metrics + Grafana dashboards

See the coordinator setup and worker deployment guides for detailed instructions.