Economy¶
The economy schema centers on a single market-transaction table (enhanced_market_transactions) that uses the lowercase commodity names also used by station inventory and the frontend. Per-station market state is held by Market, with a live MarketPrice book and a time-series PriceHistory. Catalog metadata for tradable resources lives in the Resource model.
Resource¶
Source: services/gameserver/src/models/resource.py
Purpose: Catalog row for a tradable resource type with quality, weight, base value, and market behavior.
Fields:
| name | type | constraints | notes |
|---|---|---|---|
| id | UUID | PK | |
| type | Enum resource_type |
not null | ORE, BASIC_FOOD, GOURMET_FOOD, FUEL, TECHNOLOGY, EXOTIC_TECHNOLOGY, LUXURY_GOODS, POPULATION, QUANTUM_SHARDS, QUANTUM_CRYSTALS, COMBAT_DRONES, PRISMATIC_ORE, PHOTONIC_CRYSTALS |
| name | String(100) | not null | |
| description | String | nullable | |
| base_value | Integer | not null | credits per unit |
| quality | Enum resource_quality |
default STANDARD | LOW/STANDARD/HIGH/PREMIUM/EXOTIC |
| value_multiplier | Float | default 1.0 | quality modifier |
| weight | Float | default 1.0 | cargo units |
| trade_volume | Integer | default 100 | daily |
| price_volatility | Float | default 0.1 | |
| base_production_rate | Float | default 1.0 | |
| production_difficulty | Integer | default 1 | 1-10 |
| special_attributes | JSONB | default {} | |
| required_technology | String | nullable | |
| is_active | Boolean | default true |
Naming convention: the ResourceType enum uses UPPER_CASE names (BASIC_FOOD, TECHNOLOGY, POPULATION) for catalog identity. Trading paths and the API surface refer to commodities by their canonical lowercase string aliases (organics, equipment, colonists, …), which are also the keys used by enhanced_market_transactions, station inventory JSONB, and the frontend.
Market¶
Source: services/gameserver/src/models/resource.py
Purpose: Per-station market state — inventory, prices, modifiers, history.
Fields:
| name | type | constraints | notes |
|---|---|---|---|
| id | UUID | PK | |
| station_id | UUID FK stations.id | not null, CASCADE | |
| specialization | String | nullable | |
| size | Integer | default 5 | 1-10 |
| tax_rate | Float | default 0.05 | |
| economic_status | String | default stable |
boom/bust/stable |
| resource_availability | JSONB | default {} | resource_type → quantity |
| resource_prices | JSONB | default {} | resource_type → price |
| price_modifiers | JSONB | default {} | |
| daily_volume | JSONB | default {} | |
| price_history | JSONB | default [] | |
| black_market | Boolean | default false | |
| special_offers, trade_restrictions | JSONB | defaults |
Relationships: station (1:1, FK CASCADE); transactions → MarketTransaction (1:many).
MarketTransaction (enhanced_market_transactions)¶
Source: services/gameserver/src/models/market_transaction.py
Purpose: Trade-record table that uses string commodity names and snapshots station prices at trade time. This is what admin/economy reports query.
Fields:
| name | type | constraints | notes |
|---|---|---|---|
| id | UUID | PK | |
| player_id | UUID FK players.id | nullable, SET NULL | |
| station_id | UUID FK stations.id | nullable, SET NULL | |
| transaction_type | Enum TransactionType |
not null | buy/sell/transfer/admin_adjustment |
| commodity | String(50) | not null | lowercase string (food, tech, ore, fuel, …) |
| quantity, unit_price, total_value | Integer | not null | |
| station_buy_price, station_sell_price, station_quantity | Integer | nullable | snapshots |
| sector_id | Integer | nullable | human-readable |
| sector_uuid | UUID FK sectors.id | nullable, SET NULL | |
| timestamp | DateTime | server default now, indexed | |
| profit_margin, market_impact | Float | nullable | analytics |
| admin_notes | String(500) | nullable | |
| flagged_suspicious | Boolean | default false | |
| reviewed_by | UUID FK users.id | nullable, SET NULL | admin who reviewed |
Relationships: player, station, sector, reviewer.
Indexes: timestamp, commodity, player_id, station_id.
MarketPrice¶
Source: services/gameserver/src/models/market_transaction.py
Purpose: Live price book per (station, commodity).
Fields: id, station_id FK (CASCADE), commodity String, buy_price, sell_price, quantity, previous_buy_price, previous_sell_price, price_trend Float, volatility Float, demand_level Float (default 1.0), supply_level Float (default 1.0), last_transaction_at, daily_volume, price_floor, price_ceiling, alert_threshold, updated_at, created_at.
Unique index: (station_id, commodity).
PriceHistory¶
Source: services/gameserver/src/models/market_transaction.py
Purpose: Time-series snapshots (hourly/daily/weekly) of station-commodity prices and volume.
Key fields: station_id FK CASCADE, commodity, buy_price, sell_price, quantity, daily_volume, transactions_count, average_transaction_size, demand_level, supply_level, market_efficiency, snapshot_date, snapshot_type.
Indexes: (snapshot_date, commodity), (station_id, snapshot_date).
EconomicMetrics¶
Source: services/gameserver/src/models/market_transaction.py
Purpose: Daily/weekly/monthly aggregate health stats for the economy admin dashboard.
Notable fields: date (unique), metric_type, total_trade_volume, total_transactions, average_transaction_value, total_credits_in_circulation, credits_in_player_accounts, credits_in_npc_accounts, credit_velocity, economic_health_score (0-1), inflation_rate, average_profit_margin, market_volatility, most_traded_commodity, least_traded_commodity, commodity_price_index, most_active_sector, most_valuable_station FK, economic_disparity_index, richest_player_credits, median_player_credits, total_players_trading, new_traders, calculated_at.
PriceAlert¶
Source: services/gameserver/src/models/market_transaction.py
Purpose: Admin-triggered alerts on suspicious or notable price/volume movements.
Key fields: station_id FK CASCADE, commodity, alert_type (price_spike/price_drop/high_volume/low_supply), threshold_value, current_value, severity (low/medium/high/critical), message, suggested_action, is_active, triggered_at, acknowledged_by FK users.id, acknowledged_at, resolved_at, auto_resolve, resolve_threshold.
Indexes on is_active and triggered_at.
Station-side pricing¶
Station-class trading patterns (who buys/sells what) are encoded directly on Station via the commodities JSONB blob (buys, sells, current_price, production_rate, etc.) and the get_trading_pattern() / update_commodity_* helpers driven by StationClass. See ./entities.md for the full Station model. The 12 classes (CLASS_0…CLASS_11) cover Sol special, mining, agricultural, industrial, distribution, collection, mixed market, exchange, premium buyer (Black Hole), premium seller (Nova), luxury, advanced tech.