# wanchenrui/powerscope architecture

> Architecture diagram of the GitHub repository wanchenrui/powerscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wanchenrui/powerscope
- Repository: https://github.com/wanchenrui/powerscope

## Overview

PowerScope is a desktop tool for live MCU and power-electronics firmware debugging. Its main workflow is to load a device profile, connect over serial, load firmware ELF symbols, then monitor variables and plot or record samples. The graph also preserves documented tuning, safety, AI, and project-adaptation capabilities. Evidence is limited to the README and indexed excerpts; links for unsampled subsystems are included only where README documentation supports them.

Main entry points: [`power_scope/ui/power_main_window.py`](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/power_main_window.py) (Desktop UI), [`power_scope/session/session_controller.py`](https://github.com/wanchenrui/powerscope/blob/main/power_scope/session/session_controller.py) (Session Controller), [`power_scope/main.py`](https://github.com/wanchenrui/powerscope/blob/main/power_scope/main.py) (PowerScope App), [`power_scope/ui/variable_inspector_view.py`](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/variable_inspector_view.py) (Variable Monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and Profiles"]
  node_app["PowerScope App<br/>[main.py]"]
  node_profile["Device Profile<br/>[device_profile.py]"]
  node_ui["Desktop UI"]
  node_elf["ELF / DWARF Parser<br/>[elf_parser.py]"]
  node_variables["Variable Monitor"]
  node_plots["Live Plots<br/>[scope_view.py]"]
  node_recorder["Wave Recording"]
end

subgraph group_session["Session and Transport"]
  node_session["Session Controller"]
  node_transport["Serial Transport"]
  node_mock["Mock Transport<br/>[mock_transport.py]"]
end

subgraph group_firmware["Protocol and Firmware"]
  node_protocol["Protocol Engine<br/>[protocol_engine.py]"]
  node_events["Event Bus<br/>[event_bus.py]"]
  node_native["Native C Core<br/>[debug_protocol.c]"]
  node_stub["MCU Debug Stub<br/>[debug_monitor.c]"]
end

subgraph group_analysis["Analysis and Tuning"]
  node_safety["Safety Controller"]
  node_tuning["PID Tuning Engine<br/>[tuning_engine.py]"]
  node_simulator["Power Simulator<br/>[power_simulator.py]"]
end

subgraph group_assist["AI and Project Tools"]
  node_ai["AI Assistant<br/>[llm_engine.py]"]
  node_msg["MSG Commands<br/>[msg_service.py]"]
  node_upgrade["Serial Upgrade"]
  node_dashboard["Power Dashboard"]
end

node_engineer(("Engineer"))
node_target[("Firmware State")]

node_engineer -->|"launches"| node_app
node_profile -->|"configures"| node_app
node_app -->|"opens"| node_ui
node_engineer -->|"loads firmware"| node_elf
node_elf -->|"supplies symbols"| node_variables
node_profile -->|"maps variables"| node_variables
node_variables -->|"selects samples"| node_plots
node_plots -->|"records samples"| node_recorder
node_ui -->|"manages connection"| node_session
node_session -->|"creates"| node_transport
node_session -->|"creates"| node_mock
node_session -->|"parses received data"| node_protocol
node_protocol -->|"publishes frames"| node_events
node_session -->|"publishes state"| node_events
node_transport -->|"exchanges serial data"| node_stub
node_stub -->|"reads and writes"| node_target
node_native -->|"provides CRC and codec"| node_protocol
node_ui -->|"uses guarded writes"| node_safety
node_ui -->|"requests tuning"| node_tuning
node_ui -->|"runs simulation"| node_simulator
node_ui -->|"requests assistance"| node_ai
node_ui -->|"provides commands"| node_msg
node_ui -->|"provides upgrade tools"| node_upgrade
node_ui -->|"provides power view"| node_dashboard

click node_app "https://github.com/wanchenrui/powerscope/blob/main/power_scope/main.py"
click node_profile "https://github.com/wanchenrui/powerscope/blob/main/power_scope/config/device_profile.py"
click node_ui "https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/power_main_window.py"
click node_elf "https://github.com/wanchenrui/powerscope/blob/main/power_scope/debug/elf_parser.py"
click node_variables "https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/variable_inspector_view.py"
click node_plots "https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/scope_view.py"
click node_recorder "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/session_recorder.py"
click node_session "https://github.com/wanchenrui/powerscope/blob/main/power_scope/session/session_controller.py"
click node_transport "https://github.com/wanchenrui/powerscope/blob/main/power_scope/transport/serial_transport.py"
click node_mock "https://github.com/wanchenrui/powerscope/blob/main/power_scope/transport/mock_transport.py"
click node_protocol "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/protocol_engine.py"
click node_events "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/event_bus.py"
click node_native "https://github.com/wanchenrui/powerscope/blob/main/power_core/src/debug_protocol.c"
click node_stub "https://github.com/wanchenrui/powerscope/blob/main/mcu_debug_stub/debug_monitor.c"
click node_safety "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/safety_controller.py"
click node_tuning "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/tuning_engine.py"
click node_simulator "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/power_simulator.py"
click node_ai "https://github.com/wanchenrui/powerscope/blob/main/power_scope/llm/llm_engine.py"
click node_msg "https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/msg_service.py"
click node_upgrade "https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/serial_upgrade_view.py"
click node_dashboard "https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/power_dashboard_view.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_profile,node_ui,node_elf,node_variables,node_plots,node_recorder toneBlue
class node_session,node_transport,node_mock,node_target toneAmber
class node_protocol,node_events,node_native,node_stub toneMint
class node_safety,node_tuning,node_simulator toneRose
class node_ai,node_msg,node_upgrade,node_dashboard,node_engineer toneIndigo
```

## Components

### Desktop and Profiles

- [PowerScope App](https://github.com/wanchenrui/powerscope/blob/main/power_scope/main.py): `power_scope/main.py`
- [Device Profile](https://github.com/wanchenrui/powerscope/blob/main/power_scope/config/device_profile.py): `power_scope/config/device_profile.py`
- [Desktop UI](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/power_main_window.py): `power_scope/ui/power_main_window.py`
- [ELF / DWARF Parser](https://github.com/wanchenrui/powerscope/blob/main/power_scope/debug/elf_parser.py): `power_scope/debug/elf_parser.py`
- [Variable Monitor](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/variable_inspector_view.py): `power_scope/ui/variable_inspector_view.py`
- [Live Plots](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/scope_view.py): `power_scope/ui/scope_view.py`
- [Wave Recording](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/session_recorder.py): `power_scope/core/session_recorder.py`

### Session and Transport

- [Session Controller](https://github.com/wanchenrui/powerscope/blob/main/power_scope/session/session_controller.py): `power_scope/session/session_controller.py`
- [Serial Transport](https://github.com/wanchenrui/powerscope/blob/main/power_scope/transport/serial_transport.py): `power_scope/transport/serial_transport.py`
- [Mock Transport](https://github.com/wanchenrui/powerscope/blob/main/power_scope/transport/mock_transport.py): `power_scope/transport/mock_transport.py`

### Protocol and Firmware

- [Protocol Engine](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/protocol_engine.py): `power_scope/core/protocol_engine.py`
- [Event Bus](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/event_bus.py): `power_scope/core/event_bus.py`
- [Native C Core](https://github.com/wanchenrui/powerscope/blob/main/power_core/src/debug_protocol.c): `power_core/src/debug_protocol.c`
- [MCU Debug Stub](https://github.com/wanchenrui/powerscope/blob/main/mcu_debug_stub/debug_monitor.c): `mcu_debug_stub/debug_monitor.c`

### Analysis and Tuning

- [Safety Controller](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/safety_controller.py): `power_scope/core/safety_controller.py`
- [PID Tuning Engine](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/tuning_engine.py): `power_scope/core/tuning_engine.py`
- [Power Simulator](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/power_simulator.py): `power_scope/core/power_simulator.py`

### AI and Project Tools

- [AI Assistant](https://github.com/wanchenrui/powerscope/blob/main/power_scope/llm/llm_engine.py): `power_scope/llm/llm_engine.py`
- [MSG Commands](https://github.com/wanchenrui/powerscope/blob/main/power_scope/core/msg_service.py): `power_scope/core/msg_service.py`
- [Serial Upgrade](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/serial_upgrade_view.py): `power_scope/ui/serial_upgrade_view.py`
- [Power Dashboard](https://github.com/wanchenrui/powerscope/blob/main/power_scope/ui/power_dashboard_view.py): `power_scope/ui/power_dashboard_view.py`

### Other components

- **Engineer**
- **Firmware State**

## Connections

- Engineer → PowerScope App: launches (evidence: `README.md`)
- Device Profile → PowerScope App: configures (evidence: `power_scope/main.py`)
- PowerScope App → Desktop UI: opens (evidence: `power_scope/main.py`)
- Engineer → ELF / DWARF Parser: loads firmware (evidence: `README.md`)
- ELF / DWARF Parser → Variable Monitor: supplies symbols (evidence: `README.md`)
- Device Profile → Variable Monitor: maps variables (evidence: `README.md`)
- Variable Monitor → Live Plots: selects samples (evidence: `README.md`)
- Live Plots → Wave Recording: records samples (evidence: `README.md`)
- Desktop UI → Session Controller: manages connection (evidence: `README.md`)
- Session Controller → Serial Transport: creates (evidence: `power_scope/session/session_controller.py`)
- Session Controller → Mock Transport: creates (evidence: `power_scope/session/session_controller.py`)
- Session Controller → Protocol Engine: parses received data (evidence: `power_scope/session/session_controller.py`)
- Protocol Engine → Event Bus: publishes frames (evidence: `power_scope/core/protocol_engine.py`)
- Session Controller → Event Bus: publishes state (evidence: `power_scope/session/session_controller.py`)
- Serial Transport → MCU Debug Stub: exchanges serial data (evidence: `README.md`)
- MCU Debug Stub → Firmware State: reads and writes (evidence: `README.md`)
- Native C Core → Protocol Engine: provides CRC and codec (evidence: `power_scope/core/protocol_engine.py`)
- Desktop UI → Safety Controller: uses guarded writes (evidence: `README.md`)
- Desktop UI → PID Tuning Engine: requests tuning
- Desktop UI → Power Simulator: runs simulation
- Desktop UI → AI Assistant: requests assistance
- Desktop UI → MSG Commands: provides commands (evidence: `power_scope/ui/power_main_window.py`)
- Desktop UI → Serial Upgrade: provides upgrade tools (evidence: `power_scope/ui/power_main_window.py`)
- Desktop UI → Power Dashboard: provides power view (evidence: `power_scope/ui/power_main_window.py`)
