Content: New Smart Grid Energy Lab v1.0 (Design Completed, Development Pending)

The complete design for **Smart Grid Energy Lab v1.0** (ESP32-based) has been finalized, but no implementation work has started yet.
This epic tracks all end-to-end development needed to deliver a fully functional v1.0 featuring campaign/mission structure, difficulty system, gamification, JSON-driven configuration, expanded REST API, integrated defense/vulnerability mechanics, and a significantly improved web UI.

**Design reference:**
“Smart Grid Energy Lab v1.0 — Complete Design & Implementation Plan”
(Last updated: Feb 6, 2026)

## Key Features in v1.0

- Multiple learning paths: **Red**, **Blue**, **Admin**, **Architect**
- Preset difficulty levels + fully custom configuration
- Campaign system with mission unlocking and progress tracking
- Gamification: XP, levels, achievements, leaderboards
- Multiple valid solution paths per mission
- **100% JSON-driven configuration** (no hardcoded values)
- Modern web UI: mission dashboard, config panel, leaderboard
- Audit logging, forensics view, defense system (DP/AP/SS)
- Configurable vulnerability exposure (IDOR, race conditions, tampering)

## Scope / Deliverables

- **Core ESP32 modules**
- Config Manager (LittleFS JSON load/save, presets, import/export)
- Campaign Engine (mission locking, objective evaluation, progress)
- Gamification Engine (XP calc, level-ups, achievements, leaderboard)

- **Configuration system**
- Load/save from LittleFS
- Preset switching (Easy / Intermediate / Hard / Expert)
- Custom sliders/parameters
- Import/export functionality

- **Missions & Campaigns**
- Lock/unlock logic
- Multi-path objective validation
- Reward & progression calculation

- **API expansion** (JSON REST)
- Mission, campaign, gamification, config, defense endpoints
- Proper authentication & role-based access control

- **Defense & Vulnerability integration**
- Configurable DP/AP/SS costs & activation rules
- Optional auto-defense behaviors
- Lab-mode vulnerabilities controlled via config

- **Web Frontend**
- Mission dashboard with real-time progress
- Leaderboard view
- Configuration panel with live preview
- JavaScript controllers + WebSocket/real-time updates

- **Data & persistence**
- Persistent models (campaign progress, gamification state)
- Audit log streaming
- (Optional) snapshot / rollback capability

- **Testing**
- Unit tests (esp. config parsing, reward logic, objective checks)
- Integration tests (campaign flow, API behavior)
- Security-focused test cases
- Performance validation (config load time, API latency)

## Acceptance Criteria

- System boots and loads **all major behavior from JSON config** (minimal to no hard-coded values)
- Difficulty presets + custom configuration are fully functional
- Campaign progression works (missions lock/unlock correctly, completion persists)
- Gamification state (XP, level, achievements, leaderboard) persists across reboots
- New API endpoints return correct JSON and enforce authentication & authorization
- Vulnerabilities appear / disappear and defense mechanisms activate according to config
- Web UI shows mission dashboard, leaderboard, and config panel correctly
- Baseline performance targets are achieved (config load < 800 ms, API responses < 150 ms average)

## Suggested Implementation Phases

1. Config system + Campaign Engine + Gamification Engine (core backend logic)
2. Web UI foundation + mission dashboard + leaderboard
3. Simulation parameter control (meters, time acceleration, billing logic)
4. Expanded API endpoints + auth refactoring if needed
5. Defense system + vulnerability toggles integration
6. Comprehensive testing (unit, integration, security, performance)
7. Documentation (README, config schema, API spec, user guide)
8. Optimization, memory tuning & final polish

## Dependencies & Risks

- **ESP32 memory constraints**
→ LittleFS size, JSON parsing memory usage, concurrent WebSocket load

- **API surface growth**
→ May require cleaner router / middleware / auth refactoring

- **Vulnerability vs Defense separation**
→ Must clearly isolate lab-mode weaknesses from active defense controls

- **JSON config complexity**
→ Risk of schema drift or overly nested documents

- **Real-time UI performance**
→ WebSocket stability and rendering efficiency on low-power clients

infos in ESP32-LABs/ESP32-H4CK-GRD/SMART_GRID_PLAN.md

Start by reading ESP32-LABs/ESP32-H4CK-GRD/SMART_GRID_PLAN.md, which contains the design reference and implementation phases. The issue is a broad v1.0 epic with no named source files or tests; completion requires all listed acceptance criteria, so it should be split into smaller, independently testable tasks first.

Written by the indexing model from the issue text.