This page covers the project structure, architectural layers, module dependencies, and the core infrastructure of wiRedPanda. --- ## Project Structure ``` 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 ``` ### Key Organizational Principles - **One element = one `.h`/`.cpp` pair** in `App/Element/GraphicElements/`. - **Source file lists** live in `CMakeSources.cmake` (not `CMakeLists.txt`) and must stay **alphabetically sorted**. - **All builds go into `build/`** — never build in the source tree. ### Build Presets The project uses **CMake Presets** (`CMakePresets.json`) to standardize build configurations: ```bash # 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 | ### Incremental Builds and Cache - **ccache**: caches previous compilations. Partial recompilations are much faster. - **mold**: modern parallel linker, significantly faster than `ld` or `gold`. - **Unity Build**: source files are grouped to reduce compilation overhead (configurable in CMake). - **Precompiled Headers (PCH)**: `pch.h` precompiles the most-used Qt headers. > **Tip**: the first build may take several minutes. Subsequent builds with ccache take seconds. --- ## Architectural Layers 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. ### Module Dependency Diagram ``` ┌──────────────┐ │ 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. --- ## Core Layer (App/Core) ### Application `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. ### Enums and Central Types `App/Core/Enums.h` defines the fundamental enums: #### `Status` (4-state logic) ```cpp 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](Simulation-Engine-Internals.md) for details on how these states are processed. #### `ElementType` 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) #### `ElementGroup` Groups elements in the UI palette: - `Gate` (logic gates), `Memory` (flip-flops and latches) - `Input`, `Output`, `StaticInput` (VCC/GND) - `Mux`, `IC`, `Other` #### `WirelessMode` Wireless node modes: `None` (default), `Tx` (transmitter), or `Rx` (receiver). ### Settings `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 ### Themes `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. --- ## See Also - [Element System](Element-System.md) — The element layer in detail - [Simulation Engine Internals](Simulation-Engine-Internals.md) — The simulation layer in detail - [Scene and UI](Scene-and-UI.md) — The scene and UI layers in detail - [Developer Guide](Developer-Guide.md) — Learning path, starter tasks, tips