Energy Market Simulation Game (EMSG)

MVP Version | Sprint 23 (December 2025)

A web-based energy market simulation platform for educational and training purposes. Players manage virtual power plants, forecast market conditions, and compete in realistic energy markets with dynamic pricing.

---

Features

🎮 Core Gameplay

• Unified Solo & Shared Flow: Consistent phase-based experience for individual and cohort play
• Briefing Phase: Scenario introduction with objectives before time pressure begins
• Real-time Market Simulation: Double-auction market clearing with supply/demand dynamics
• Device Management: Solar, Wind, Gas, Battery, Hydro with realistic constraints
• Multi-round Scenarios: Progress through time-based energy market challenges with structured pacing
• Round Results & Advancement: Players control pacing with "Continue" buttons between rounds
• Weighted Scoring System: Configurable KPI weights (profit, imbalance, curtailment)
• Leaderboard & Comparisons: Track performance and learn from strategies

🛠️ Scenario Designer (KSE)

• Visual Editor: Drag-and-drop device configuration
• Market Parameters: Price floors/caps, volumes, variability
• Grid Simulation: Multi-zone grids with transmission constraints (ATC matrices)
• Enhanced Events System: 8 event types including grid link ATC reduction
• Preview & Validation: Real-time supply/demand curve visualization
• Import/Export: JSON-based scenario sharing
• Player Types: Define role-specific device assignments for shared sessions

👥 Trainer Tools

• Campaign Management: Sequential scenario progressions
• Cohort Administration: Group management, CSV import, player type configuration
• Live Monitoring: Real-time participant tracking with per-type submit status
• Session Controls: Start/pause/freeze rounds, force round end
• Shared Market Sessions: All players trade in unified market with balanced roles
• Performance Analytics: Weighted scoring, final rankings, round history

📊 Analytics

• Player Dashboard: Balance tracking, device portfolios, forecast accuracy
• Round-by-Round Results: Individual KPIs with active event displays
• Cumulative Performance: Final scenario results with round history accordion
• Comparison View: Side-by-side player strategy analysis
• Activity Logs: Comprehensive audit trail
• Performance Metrics: Profit, imbalance penalties, curtailment costs

---

Quick Start

Prerequisites

• Docker & Docker Compose
• Git

1. Clone and Setup

git clone https://github.com/MatthiasHertel21/energy-game.git
cd energy-game
cp .env.example .env

2. Launch

docker-compose up -d --build

3. Access

• Frontend: http://localhost
• API Docs: http://localhost/api/docs
• Health: http://localhost/api/health

4. First Login

• Register at /register (first user gets player role)
• Admin can create invites via /api/docs → POST /api/admin/invites
• Assign roles: player, trainer, designer, admin

---

Architecture

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│   React     │─────▶│ Flask API    │─────▶│  PostgreSQL  │
│   (Vite)    │      │ (REST+WS)    │      │   (State)    │
└─────────────┘      └──────────────┘      └──────────────┘
                            │
                            ├─────▶ Redis (Sessions)
                            └─────▶ Traefik (Routing)

Stack

• Frontend: React 18, Material-UI, D3.js, Socket.io-client
• Backend: Flask, SQLAlchemy, Flask-SocketIO, Gunicorn
• Database: PostgreSQL 15 (state), Redis 7 (sessions/cache)
• Proxy: Traefik v2 with Let's Encrypt
• Testing: Pytest (backend), Cypress (E2E)

Key Components

• Engine (backend/app/engine.py): Market clearing algorithm (double-auction)
• Device Types (backend/app/device_types.py): Power plant models
• Sessions (backend/app/sessions.py): Game state management
• KSE (frontend/src/pages/KSE.jsx): Scenario editor
• Player (frontend/src/pages/Player.jsx): Forecast interface

---

Performance

Baseline Metrics (Sprint 20, 100 concurrent users, Locust load test):

• Response Time: p50=4ms, p95=8ms, p99=15ms (excellent)
• Throughput: ~50 req/s sustained
• Known Issue: 93% error rate due to rate limiting (429) and missing auth in test setup
• Action: Sprint 21 will fix Locust auth and adjust rate limits for testing

See docs/PERFORMANCE_RESULTS.md for detailed metrics.

---

Testing

Backend Unit Tests

# In Docker
docker-compose exec backend python -m pytest tests/ -v

# Specific tests
docker-compose exec backend python -m pytest tests/test_engine.py -v

Coverage:

• Market clearing algorithm
• Device models and validation
• Curtailment priority logic
• Use case scenarios

Frontend E2E Tests (Cypress)

cd frontend
npm run cy:open  # Interactive
npm run cy:run   # Headless

Test Coverage (Sprint 20): 20 E2E specs including:

• smoke.cy.js - Core user flows
• trainer.cy.js - Session management
• player.cy.js - Forecast submission
• kse-devices.cy.js - Device editor
• a11y.cy.js - Accessibility audits
• campaign-timeline.cy.js - Campaign navigation
• cohorts-import.cy.js - CSV import
• comparison.cy.js - Leaderboard comparison

All 20 specs passing as of Sprint 20.

---

Database & Deployment

See docs/DEPLOYMENT.md for details on:

• Database migrations (flask db upgrade)
• Backup procedures (backend/scripts/backup.sh)
• Production deployment
• Docker Compose stability

---

Known Issues

Sprint 21 Focus (14 KSE UI/UX Issues):

• KSE-1 (P0): Market/Preview tabs broken in KSE editor
• KSE-2 (P0): Device constraint validation missing
• KSE-3 through KSE-14: UI/UX refinements for MVP quality

See docs/backlog.md (Sprint 21 section) and docs/open-issues.md for full details.

DevOps:

• Docker Compose stability: Use deploy.sh with retry logic (see docs/DEPLOYMENT.md)

---

Documentation

• docs/concept.md - Architecture & MVP scope
• docs/usecases.md - Functional requirements
• docs/SPRINT_*_PLAN.md - Development roadmap (23 sprints: 1-20 complete, 21 active, 22-23 planned)
• docs/SPRINT_*_SUMMARY.md - Sprint retrospectives
• docs/QA_CHECKS.md - Pre-launch checklist
• docs/PERFORMANCE_RESULTS.md - Load test baseline
• docs/PLANUNGSSTAND_ANALYSE.md - Planning analysis (Sprint 20)

Role Handbooks

• docs/guide/player-handbook.md - Player Guide
• docs/guide/trainer-handbook.md - Trainer Guide
• docs/guide/designer-handbook.md - Designer/KSE Guide
• docs/guide/admin-handbook.md - Admin Guide

---

Last Updated: Sprint 21 (2025-11-20) - flask db migrate -m "init" - flask db upgrade

• Weitere Änderungen:
  • flask db migrate -m "change"
  • flask db upgrade

Hinweis: create_all() wurde entfernt. Bitte Migrationen nutzen.

Docker/CI Tipp:

• Inside backend container: docker compose exec backend flask db upgrade
• Helper Script: backend/scripts/migrate.sh führt init (falls nötig), migrate und upgrade aus.

Backups

• Script: backend/scripts/backup.sh (schreibt /backup/emsg_YYYYmmdd_HHMMSS.dump)
• Beispiel‑Cron (Host):
  • 0 2 * * * docker compose exec -T backend bash -lc "/app/scripts/backup.sh"
• Log‑Rotation: Backend läuft unter Gunicorn; ergänze systemweite logrotate oder Docker‑Logging‑Driver nach Bedarf.

Tests

Backend Unit Tests

# In Docker
docker compose exec backend python -m pytest tests/ -v

# Spezifische Tests
docker compose exec backend python -m pytest tests/test_engine.py -v
docker compose exec backend python -m pytest tests/test_device_types.py -v

Frontend E2E Tests (Cypress)

cd frontend

# Interaktive UI
npm run cy:open

# Headless
npm run cy:run

# Spezifische Tests
npm run cy:run -- --spec "cypress/e2e/kse-devices.cy.js"

Tests verfügbar:

• smoke.cy.js - Login, KSE Preview, Trainer Start, Player Forecast
• trainer.cy.js - Session Management, Shared Market
• player.cy.js - Full Forecast, Submit
• comparison.cy.js - Leaderboard, Comparison Dashboard
• kse-import.cy.js - KSE JSON Import/Export
• cohorts-import.cy.js - Cohort CSV Import
• kse-devices.cy.js - Device Model (Coal, Nuclear, Solar, Battery, Loads)
• replay.cy.js - Replay Mode (derzeit instabil/geskippt)

Performance Tests (Locust)

cd backend/tests/perf
locust -f locustfile.py --host=http://localhost