Star Citizen Trading

A Node.js web application that displays real-time commodity trading data for Star Citizen, sourced from the UEX Corp API.

Features

• 📊 Real-time commodity prices from UEX Corp API
• 🔄 Auto-refresh data every minute (configurable)
• 💰 Profit calculations for all trading routes
• 🗺️ System/terminal mapping with location codes
• 📱 Touch Portal interface for custom SCU capacities
• 🎨 Dark theme optimized for readability
• 📝 Comprehensive logging with Winston
• 🛡️ Robust error handling with retry logic
• ⚡ Production-ready code with tests

Installation

Prerequisites

• Node.js 20+ (tested with v20.19.2)
• npm

Setup

1. Clone the repository:

git clone https://github.com/dodoslavn/StarCitizen_Trading.git
cd StarCitizen_Trading/StarCitizen_Trading

2. Install dependencies:

npm install

3. Create configuration file:

cp config.json.example config.json

4. Edit config.json with your settings (see Configuration section)

5. Start the server:

npm start

The server will be available at http://localhost:3000 (or your configured port).

Configuration

Edit config.json to customize the application:

{
  "http_server": {
    "ip_listen": "127.0.0.1",
    "port_listen": "3000"
  },
  "api": {
    "base_url": "https://api.uexcorp.space/2.0",
    "endpoints": {
      "prices_all": "/commodities_prices_all",
      "solar_systems_all": "/star_systems",
      "terminals_all": "/terminals"
    },
    "timeout": 10000,
    "retries": 3
  },
  "cache": {
    "refresh_interval_minutes": 1
  },
  "logging": {
    "level": "info",
    "file": "trading.log",
    "console": true
  }
}

Configuration Options

Option	Description	Default
http_server.ip_listen	IP address to bind to	127.0.0.1
http_server.port_listen	Port number	3000
api.timeout	API request timeout (ms)	10000
api.retries	Number of retry attempts	3
cache.refresh_interval_minutes	Data refresh frequency	1
cache.stale_after_minutes	Age (minutes) after which a terminal's price data is grayed out as outdated	1440
cache.very_stale_after_minutes	Age (minutes) after which a terminal's price data is grayed out further as very outdated	4320
logging.level	Log level (error/warn/info/debug)	info
logging.file	Log file path	trading.log
logging.console	Enable console logging	true

Usage

Web Interface

Navigate to http://localhost:3000 to see:

• Main Page (/): All commodities with buy/sell prices and profit calculations
• About (/about): Information about the website
• Touch Portal (/touchportal/[scu]/[system]): Optimized for specific cargo capacities
• Refresh (/refresh): Manually trigger data refresh

API Endpoints

Endpoint	Description
/	Main trading data page
/about	About page
/default.css	Stylesheet
/favicon.ico	Favicon
/refresh	Trigger manual data refresh
/touchportal/[scu]	Touch portal for specific SCU
/touchportal/[scu]/[system]	Touch portal filtered by system

Development

Running Tests

npm test

Linting

npm run lint        # Check for issues
npm run lint:fix    # Auto-fix issues

Development Mode

npm run dev

Max Inventory Scan

The commodity table shows an estimated (or, once scanned, confirmed) max SCU capacity per terminal. Confirmed values come from a separate one-shot script that scans UEX's price history:

npm run scan-inventory

It writes max_inventory.json, which the server reads on startup. This is run daily by the Scan max inventory GitHub Action (see .github/workflows/scan-max-inventory.yml), which commits the updated file back to master and thereby triggers a redeploy. The script always does a full pass (~2-3 minutes) and exits non-zero if too many per-pair fetches fail during the run, so an incomplete file never gets committed.

Architecture

Project Structure

StarCitizen_Trading/
├── server.js              # Main server entry point
├── scan-max-inventory.js  # Standalone max-inventory history scan (see above)
├── config.js              # Shared config.json loader
├── functions.js           # Core business logic and HTTP handlers
├── html.js                # HTML generation and rendering
├── dataCache.js           # Data caching management
├── logger.js              # Winston logger configuration
├── favicon.js             # Base64 encoded favicon
├── config.json            # Configuration (create from .example)
├── config.json.example    # Example configuration
├── max_inventory.json     # Output of scan-max-inventory.js
├── package.json           # Dependencies and scripts
├── .eslintrc.json         # ESLint configuration
└── tests/                 # Unit tests
    ├── dataCache.test.js
    └── html.test.js

Key Components

DataCache

Manages in-memory caching of:

• Commodity price data
• System/terminal mappings
• Profit calculations

Functions

Core business logic:

• API data fetching with retry logic
• Data normalization
• HTTP request routing
• Response generation

HTML Module

Rendering engine for:

• Commodity tables
• Profit summaries
• Touch portal interface

Improvements (v1.0.0)

This version includes major refactoring and production-ready improvements:

Code Quality

• ✅ ESLint integration with standard config
• ✅ JSDoc comments on all functions
• ✅ Unit tests with Jest
• ✅ Modular architecture with clear separation of concerns

Reliability

• ✅ Retry logic with exponential backoff
• ✅ Timeout handling for API requests
• ✅ HTTP status checking on all fetches
• ✅ Graceful error handling with fallbacks

Observability

• ✅ Winston logging replacing console.log
• ✅ Configurable log levels (debug/info/warn/error)
• ✅ File and console logging
• ✅ Request tracking with client IPs

Performance

• ✅ Replaced globals with DataCache class
• ✅ Parallel API calls where possible
• ✅ Efficient data structures

User Experience

• ✅ Better error pages (404, 503, 500)
• ✅ Graceful shutdown handling
• ✅ Configuration validation

Data Source

All trading data is sourced from the UEX Corp API, a community-driven Star Citizen resource.

License

See LICENSE for details.