OpsResearch

A full-stack optimizer for the McGraw Hill Practice Operations business simulation game. It connects to the game via WebSocket, parses game state, runs optimization algorithms across 12 business domains, and presents actionable recommendations through a React dashboard that can execute actions directly back into the game.

Features

• 12 Optimizer Modules — investment planning, market analysis, HR optimization, production planning, bid evaluation (LP solver), supply chain optimization, shipping optimization, bid simulation, demand forecasting, job shop scheduling, master planning, and scenario planning
• React Dashboard — real-time recommendations, action queue, activity feed, production manager, bid simulator, and data dictionary
• WebSocket Integration — persistent connection to the game server for live state updates and action execution
• Automated Data Collection — Playwright-based browser automation to extract game credentials and state
• Dual Format Parser — supports both activity_instance_data.json and flat gamedata.json formats
• Standalone Mode — run the optimizer from the command line for a Markdown report without the dashboard

Architecture

Data Flow

Game Server (WebSocket) ──→ GameConnectionService ──→ DataParser ──→ GameState
                                                                        │
React Dashboard ←── Socket.io ←── Express API ←── Optimizer Modules ←───┘
       │                              │
       └── Action Queue ──→ API ──→ WebSocket ──→ Game Server

Project Structure

├── src/                    # CommonJS — core logic
│   ├── models/             # 23 data model classes
│   ├── parser/             # DataParser, ModuleDataParser
│   ├── optimizer/          # 12 optimizer modules + coordinator
│   │   └── shared/         # Cross-module constants & validation
│   └── main.js             # Standalone optimizer entry point
├── server/                 # ES Modules — Express + Socket.io API
│   ├── routes/             # API route handlers
│   └── services/           # GameConnectionService
├── client/                 # ES Modules — React + Vite SPA
│   └── src/components/     # Dashboard UI components
├── data/                   # Game data files (gitignored)
├── tests/                  # Node.js built-in test runner
└── docs/                   # Documentation & data dictionary

Module System

The codebase uses two module systems:

• src/ — CommonJS (require/module.exports), set by root package.json "type": "commonjs"
• server/ and client/ — ES Modules (import/export), each with their own package.json

The server imports CommonJS optimizer modules using createRequire().

Quick Start

# Install all dependencies (root + server + client)
npm install && npm run dashboard:install

# Run the full dashboard (server on :3001 + client on :5173)
npm run dashboard

# Or run the standalone optimizer (Markdown report to console)
npm run optimize

Configuration

config.json

Game connection credentials. Generated by the automated collector or set manually:

{
  "activeModule": 4,
  "modules": {
    "4": {
      "activityInstanceId": "your-activity-instance-id",
      "userId": "your-user-id",
      "cookie": "your-session-cookie"
    }
  }
}

.env

Required only for the automated collector (npm run collect):

MCGRAW_EMAIL=your-email@example.com
MCGRAW_PASSWORD=your-password

API Endpoints

State

Method	Endpoint	Description
GET	/api/state	Get parsed game state
GET	/api/state/raw	Get raw game data
GET	/api/state/module-data	Get game template data

Optimizer

Method	Endpoint	Description
POST	/api/optimize	Run all optimizer modules
POST	/api/optimize/:module	Run a specific optimizer module
POST	/api/optimize/simulate-bid	Simulate bid outcomes
POST	/api/optimize/optimal-bid	Calculate optimal bid parameters
POST	/api/optimize/test-bid	Test a bid configuration

Actions

Method	Endpoint	Description
POST	/api/action/bid	Place a bid on a work request
POST	/api/action/hire	Hire an employee
POST	/api/action/train	Train an employee
POST	/api/action/move_employee	Move employee between departments
POST	/api/action/purchase	Set up a supplier deal
POST	/api/action/purchase_station	Buy a new station
POST	/api/action/ship	Ship product to fulfill a contract
POST	/api/action/produce	Set production schedule
POST	/api/action/cancel_production	Cancel a production run
POST	/api/action/end_turn	Advance to next week

Configuration

Method	Endpoint	Description
GET	/api/config	Get current configuration
PUT	/api/config	Update configuration
GET	/api/config/data-sources	List available data files

Collector

Method	Endpoint	Description
POST	/api/collector/start	Start automated data collection
POST	/api/collector/pull	Pull latest game data
GET	/api/collector/status	Get collector status
POST	/api/collector/disconnect	Stop the collector

Health

Method	Endpoint	Description
GET	/api/health	Server health check

Optimizer Modules

Module	Description
InvestmentPlanner	Recommends capital equipment and station purchases based on demand forecasts and ROI analysis
MarketAnalyzer	Tracks demand trends and identifies speculative market opportunities
HROptimizer	Analyzes staffing levels, recommends hiring/firing, and prioritizes employee training
ProductionPlanner	Optimizes station utilization and production scheduling across product lines
BidEvaluator	Evaluates work requests using linear programming (javascript-lp-solver) to maximize profit
SupplyChainOptimizer	Selects optimal suppliers based on price, quality, and lead time trade-offs
ShippingOptimizer	Plans contract fulfillment shipments to minimize costs and meet deadlines
BidSimulator	Simulates bid outcomes and models contract completion scenarios
DemandForecaster	Holt-Winters exponential smoothing for per-product and aggregate demand prediction
JobShopScheduler	Shifting Bottleneck heuristic for precedence-constrained production scheduling
MasterPlanner	Multi-period MILP that jointly optimizes bids, production, supply chain, and shipping
ScenarioPlanner	Monte Carlo simulation for risk analysis, VaR, and robust recommendations

Documentation

• STATUS.md — feature status matrix
• docs/data_dictionary.html — interactive data model reference (open in browser)

Testing

# Run all tests
npm test

# Run only parser tests
npm run test:parsing

# Run a single test file
node --test tests/parsing.test.js

License

ISC