-
Notifications
You must be signed in to change notification settings - Fork 25
Architecture Overview
Rodrigo Torres edited this page Apr 23, 2026
·
1 revision
This page covers the project structure, architectural layers, module dependencies, and the core infrastructure of wiRedPanda.
wiRedPanda/
├── App/ # All application source code
│ ├── Main.cpp # Entry point
│ ├── Core/ # Central infrastructure
│ │ ├── Application.cpp/h # Custom QApplication (exception handling)
│ │ ├── Common.cpp/h # Logging, Pandaception error type, helper macros
│ │ ├── Enums.cpp/h # Central enums (ElementType, Status, etc.)
│ │ ├── ItemWithId.h # Base with stable numeric identity
│ │ ├── MimeTypes.h # MIME type constants for drag-and-drop
│ │ ├── Priorities.h # Topological sorting and update priorities
│ │ ├── SentryHelpers.h # Crash reporting helpers
│ │ ├── Settings.cpp/h # Persistent settings management
│ │ ├── StatusOps.h # Four-state logic operations
│ │ ├── ThemeManager.cpp/h # Theme system (light/dark/system)
│ │ └── UpdateChecker.cpp/h # GitHub release update notifications
│ ├── Element/ # Logic elements and element factory
│ │ ├── GraphicElement.cpp/h # Abstract base class for all elements
│ │ ├── GraphicElementInput.cpp/h # Abstract base for user-interactive inputs
│ │ ├── GraphicElementSerializer.cpp # Serialization helpers
│ │ ├── ElementFactory.cpp/h # Factory singleton
│ │ ├── ElementInfo.h # Self-registration template
│ │ ├── ElementLabel.cpp/h # In-scene element label
│ │ ├── ElementMetadata.cpp/h # Element metadata and capabilities
│ │ ├── PropertyDescriptor.h # Property system
│ │ ├── IC.cpp/h # Integrated circuit (sub-circuit)
│ │ ├── ICRegistry.cpp/h # Central IC registry
│ │ └── GraphicElements/ # 31 concrete element implementations
│ ├── Simulation/ # Simulation engine
│ │ ├── Simulation.cpp/h # Main simulation loop
│ │ ├── SimulationBlocker.cpp/h # Pause mechanism
│ │ └── SimulationThrottleDisabler.cpp/h # Disables visual throttle for tests
│ ├── Nodes/ # Ports and wire connections
│ │ ├── QNEPort.cpp/h # Input/output ports
│ │ └── QNEConnection.cpp/h # Connections between ports
│ ├── Scene/ # Graphics scene, undo/redo, workspace
│ │ ├── Scene.cpp/h # Main QGraphicsScene
│ │ ├── Commands.cpp/h # Undo/redo commands
│ │ ├── Workspace.cpp/h # Workspace management
│ │ ├── ClipboardManager.cpp/h # Copy/paste
│ │ ├── ConnectionManager.cpp/h # Connection creation
│ │ ├── GraphicsView.cpp/h # Custom QGraphicsView (zoom, pan)
│ │ ├── PropertyShortcutHandler.cpp/h # Keyboard shortcuts for element properties
│ │ └── VisibilityManager.cpp/h # Element visibility control
│ ├── IO/ # File serialization
│ │ ├── Serialization.cpp/h # .panda format
│ │ ├── SerializationContext.h # Deserialization context (port ID map)
│ │ ├── VersionInfo.h # File format version predicates
│ │ ├── FileUtils.h # File utility helpers
│ │ └── RecentFiles.cpp/h # Recent files tracking
│ ├── UI/ # MainWindow, dialogs, toolbars
│ │ ├── MainWindow.cpp/h # Main window
│ │ ├── ElementPalette.cpp/h # Element palette
│ │ ├── ElementEditor.cpp/h # Property editor
│ │ ├── ElementTabNavigator.cpp/h # Tab navigation for element selection
│ │ ├── ElementContextMenu.cpp/h # Right-click context menu
│ │ ├── CircuitExporter.cpp/h # Image/PDF export
│ │ ├── FileDialogProvider.cpp/h # Testable file dialog abstraction
│ │ ├── ICDropZone.cpp/h # Drag-and-drop target for IC files
│ │ ├── LabeledSlider.cpp/h # Slider with label (e.g., clock phase)
│ │ ├── LengthDialog.cpp/h # Dialog for resizable elements
│ │ ├── ClockDialog.cpp/h # Clock configuration dialog
│ │ ├── ClockDialogUI.cpp/h # Clock dialog UI layout
│ │ ├── ElementEditorUI.cpp/h # Property editor UI layout
│ │ ├── LengthDialogUI.cpp/h # Length dialog UI layout
│ │ ├── LanguageManager.cpp/h # Language management
│ │ ├── MainWindowUI.cpp/h # Main window UI layout
│ │ ├── SelectionCapabilities.cpp/h # Selection state and capabilities
│ │ └── TrashButton.cpp/h # Delete button for selected elements
│ ├── CodeGen/ # Arduino & SystemVerilog export
│ │ ├── ArduinoCodeGen.cpp/h # Arduino/C code generation
│ │ ├── CodeGenUtils.h # Shared code generation utilities
│ │ └── SystemVerilogCodeGen.cpp/h # SystemVerilog HDL
│ ├── BeWavedDolphin/ # Waveform viewer/editor
│ │ ├── BeWavedDolphin.cpp/h # Main tool window
│ │ ├── BeWavedDolphinUI.cpp/h # UI layout
│ │ ├── WaveformView.cpp/h # Waveform rendering
│ │ ├── SignalModel.cpp/h # Signal data model
│ │ ├── SignalDelegate.cpp/h # Item delegate for signal cells
│ │ └── Serializer.cpp/h # Waveform save/load
│ └── Resources/ # SVGs, icons, translations, platform assets
│ ├── Components/ # Element SVG icons by category
│ ├── Assets/ # App logos and icons
│ ├── Fonts/ # Bundled fonts (WebAssembly)
│ ├── Freedesktop/ # Linux .desktop and icon files
│ ├── Interface/ # UI resources
│ ├── Translations/ # Translation files (.ts/.qm)
│ ├── Wasm/ # WebAssembly-specific resources
│ └── Windows/ # Windows-specific resources
├── Tests/
│ ├── Common/ # Shared test utilities (TestUtils, CircuitBuilder)
│ ├── Unit/ # Unit tests by component area
│ ├── Integration/ # IC tests, code generation tests
│ ├── System/ # System-level tests (waveform)
│ ├── BackwardCompatibility/ # Old file format test fixtures
│ ├── Resources/ # Resource validation tests
│ ├── Fixtures/ # Test .panda files
│ └── Runners/ # Unified test entry point
├── Examples/ # 21 example .panda circuit files
├── MCP/ # Model Context Protocol server
├── Scripts/ # Build and utility scripts
├── .devcontainer/ # Dev container configuration
├── .github/workflows/ # CI/CD pipelines
├── CMakeLists.txt # Top-level build configuration
├── CMakeSources.cmake # Alphabetically sorted source file lists
├── CMakePresets.json # Build presets (debug, release, asan, etc.)
├── pch.h # Precompiled header
├── README.md # Project overview and quick start
├── BUILD.md # Platform build instructions
├── CONTRIBUTING.md # Contribution guidelines
└── DEVELOPER_GUIDE.md # In-repo developer reference
-
One element = one
.h/.cpppair inApp/Element/GraphicElements/. -
Source file lists live in
CMakeSources.cmake(notCMakeLists.txt) and must stay alphabetically sorted. -
All builds go into
build/— never build in the source tree.
The project uses CMake Presets (CMakePresets.json) to standardize build configurations:
# Configure
cmake --preset debug # or: release, relwithdebinfo
# Build
cmake --build --preset debug
# Test
ctest --preset debug| Preset | Purpose |
|---|---|
debug |
Development with debug symbols |
release |
Optimized build for distribution |
relwithdebinfo |
Release with symbols (deploy with Sentry) |
coverage |
Code coverage instrumentation |
asan |
Address Sanitizer (invalid memory access) |
tsan |
Thread Sanitizer (data races) |
msan |
Memory Sanitizer (Clang only, uninitialized mem) |
ubsan |
Undefined Behavior Sanitizer |
- ccache: caches previous compilations. Partial recompilations are much faster.
-
mold: modern parallel linker, significantly faster than
ldorgold. - Unity Build: source files are grouped to reduce compilation overhead (configurable in CMake).
-
Precompiled Headers (PCH):
pch.hprecompiles the most-used Qt headers.
Tip: the first build may take several minutes. Subsequent builds with ccache take seconds.
The application follows a layered architecture:
┌─────────────────────────────────────┐
│ UI Layer (App/UI/) │ MainWindow, dialogs, toolbars
├─────────────────────────────────────┤
│ Scene Layer (App/Scene/) │ Canvas, undo/redo, clipboard
├─────────────────────────────────────┤
│ Element Layer (App/Element/) │ Logic gates, flip-flops, I/O
├──────────────┬──────────────────────┤
│ Simulation │ Nodes (Ports & │ Engine loop, topological sort,
│ (App/Sim/) │ Connections) │ port/wire data model
├──────────────┴──────────────────────┤
│ Core Layer (App/Core/) │ Enums, StatusOps, Settings
└─────────────────────────────────────┘
Data flows bottom-up: The simulation engine reads element connections and calls updateLogic() on each element in topological order. Elements compute their outputs from their inputs using the four-state logic system. The scene layer renders the results.
┌──────────────┐
│ Main.cpp │
└──────┬───────┘
│
┌──────▼───────┐
│ Application │
│ (Core/) │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼───────┐ ┌──▼──────┐ ┌───▼────────┐
│ MainWindow │ │ Scene │ │ Simulation │
│ (UI/) │ │(Scene/) │ │(Simulation/│
└──────┬───────┘ └──┬──────┘ └───┬────────┘
│ │ │
└────────────┼────────────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌───▼─────┐ ┌────▼───────┐
│ Elements │ │ Nodes │ │ Commands │
│ (Element/) │ │(Nodes/) │ │ (Scene/) │
└─────────────┘ └─────────┘ └────────────┘
│
┌──────▼──────┐
│Serialization│
│ (IO/) │
└─────────────┘
The Scene is the central point: it holds the elements, the connections, and coordinates with the Simulation. The MainWindow is the UI shell wrapping the Scene. Elements are independent of the UI and can be tested in isolation.
App/Core/Application.cpp/h is a QApplication subclass that overrides notify() to catch Pandaception and std::exception objects thrown inside Qt event handlers and display them as error dialogs — the only reliable way to handle exceptions in Qt's event loop.
App/Core/Enums.h defines the fundamental enums:
enum class Status {
Unknown = -1, // Floating / unresolved (equivalent to VHDL 'U')
Inactive = 0, // Logic LOW (0)
Active = 1, // Logic HIGH (1)
Error = 2, // Bus conflict / indeterminate (X)
};This 4-state system (inspired by VHDL's std_logic) is central to the entire simulation. Every port and connection carries a Status value. See Simulation Engine Internals for details on how these states are processed.
Each element type has a unique numeric identifier. Examples:
-
And = 5,Or = 6,Not = 4 -
DFlipFlop = 17,JKFlipFlop = 18 -
Led = 3,Display7 = 14 -
IC = 22(integrated circuit) -
Node = 23(wire junction / Tx/Rx wireless)
Groups elements in the UI palette:
-
Gate(logic gates),Memory(flip-flops and latches) -
Input,Output,StaticInput(VCC/GND) -
Mux,IC,Other
Wireless node modes: None (default), Tx (transmitter), or Rx (receiver).
App/Core/Settings.cpp/h wraps Qt's QSettings to persist user preferences:
- Window and splitter geometry/state
- Selected language
- Theme
- Recent files and autosave files
- Update check state
App/Core/ThemeManager.cpp/h manages the UI themes:
- Light: light theme
- Dark: dark theme
- System: automatically follows the OS theme
OS theme changes are detected in real time via DBus on Linux and native APIs on Windows/macOS.
- Element System — The element layer in detail
- Simulation Engine Internals — The simulation layer in detail
- Scene and UI — The scene and UI layers in detail
- Developer Guide — Learning path, starter tasks, tips
Made with ❤️ by the wiRedPanda Community
Licensed under GPL-3.0 | © 2026 GIBIS-UNIFESP