Developer Notes

The Developer Notes describe the internal architecture of GONet Wizard.

Unlike the User Guide, which focuses on concepts and usage, these pages explain how the package is implemented and how the major systems interact.

These notes are intended for contributors, advanced users, and future maintainers.

Architecture Map

Page	Focus
command-system developer notes	How commands are declared, registered, parsed, dispatched, and shared by CLI and GUI workflows.
GUI architecture developer notes	How GUI forms connect to the command system and how GUI commands request presentation.
UI runtime developer notes	How Flask, PyWebview, preview windows, Dash apps, and runtime window management fit together.
extractor architecture developer notes	How extraction outputs are composed from independent extractor components.
dashboard architecture developer notes	How the dashboard loads extraction products, discovers fields, filters data, and exports subsets.
contributor workflows developer notes	Practical recipes for adding commands, GUI forms, Dash tools, and extractors.
desktop packaging developer notes	How the desktop entry point, resource paths, PyInstaller specs, and macOS DMG wrapper fit together.
release workflow developer notes	How to build, test, and publish large installer artifacts without committing them to git.

• Command System
  • Key Code Paths
  • Primary Execution Path
  • Design Goals
  • Main Modules
  • Specification Models
  • Command Registry
  • Command Modules
  • Parser Construction
  • Handler Dispatch
  • Compatibility Layer
  • Input Expansion
  • UI-Aware Handler Wrapping
  • Smart Parse Errors
  • Parse-Time GUI Form Routing
  • Global UI Flags
  • Representative Commands
  • Adding a New Command
  • Adding a Nested Command Group
  • Exposing a Command to the GUI
  • Best Practices
  • Summary
• GUI Architecture
  • Key Code Paths
  • Form-to-Command Anchors
  • Design Goals
  • High-Level Flow
  • Launcher
  • Command Forms
  • Form Submission
  • Relationship with Command Specifications
  • Command Handlers
  • GUI Result Handling
  • Live Command Feedback Terminal
  • Preview Windows
  • Interactive Tools
  • Window Management
  • Relationship with Dash Applications
  • Static Assets and Templates
  • Adding a GUI-Accessible Command
  • Common Pitfalls
  • Summary
• UI Runtime
  • Runtime Ownership Boundaries
  • Runtime Components
  • Runtime Entry Points
  • High-Level Runtime Flow
  • Unified Flask Server
  • Launcher Routes
  • UI Result Protocol
  • Parser Integration
  • Preview System
  • Window Management
  • PyWebview Event Loop
  • Launcher Command
  • Opening Command Forms from CLI Parse Errors
  • Dash Application Runtime
  • PyWebview JavaScript API
  • Adding a Runtime-Backed UI Feature
  • Best Practices
  • Relationship to Other Documentation
  • Summary
• Extractor Architecture
  • Key Code Paths
  • Overview
  • Metadata vs Region-Based Extractors
  • Why Extractors?
  • Context-Based Execution
  • Design Philosophy
  • Extractor Dependencies
  • Automatic Dependency Resolution
  • Standard Extractors
  • Output Assembly
  • Minimal Extractor Skeleton
  • Adding New Extractors
  • Relationship with the API Reference
• Dashboard Architecture
  • Role in the Project
  • Launch Path
  • Data Model
  • Channel-Dependent Quantities
  • Image Preview Model
  • Filtering Model
  • Export Model
  • State Persistence
  • Relationship to the UI Runtime
  • Contributor Notes
  • Summary
• Contributor Workflows
  • Choosing the Right Extension Point
  • Adding a New Command
  • Adding Command Arguments
  • Adding a GUI Form for a Command
  • Adding a Preview-Producing Command
  • Adding a Dash-Based Tool
  • Adding a New Extractor
  • Adding User Documentation
  • Checklist: New Command
  • Checklist: New GUI Window
  • Checklist: New Extractor
  • Summary
• Desktop Packaging
  • Packaging Goals
  • Launch Paths
  • Distribution Boundary
  • Key Packaging Code Paths
  • Resource and Runtime Path Rules
  • Startup Readiness
  • PyInstaller Build Files
  • Dash and Plotly Assets
  • Size Cleanup Strategy
  • Unsigned macOS DMG
  • Unsigned Windows Setup.exe
  • Smoke Test Checklist
  • Troubleshooting Frozen Builds
  • Windows Packaging Notes
• Release Workflow
  • Release Artifacts Are Not Source Files
  • Recommended Build Cadence
  • Local Packaging Test
  • Manual GitHub Actions Build
  • Tagged Release Build
  • Versioned Artifact Names
  • Checksums
  • GitHub-Only Distribution
  • User-Facing Install Paths
  • macOS Signing Status
  • macOS Architecture Strategy
  • Windows Release Path
  • Release Checklist

Recommended Reading Order

For contributors, the most useful path is usually:

1. command-system developer notes — understand how commands are declared and dispatched.

2. GUI architecture developer notes — understand how GUI forms reuse those commands.

3. UI runtime developer notes — understand how windows, previews, Flask, PyWebview, and Dash are managed.

4. extractor architecture developer notes — understand how extraction outputs are assembled.

5. dashboard architecture developer notes — understand the lightweight dashboard data/plot/filter/export flow.

6. contributor workflows developer notes — use the practical recipes when adding features.

7. desktop packaging developer notes — review packaging rules when changing resource paths, GUI startup, or build scripts.

8. release workflow developer notes — review release cadence and artifact handling before publishing installers.

The dashboard is intentionally treated as a more standalone subsystem, but a lightweight architecture note is included for contributors who need to work on its data-loading, plotting, filtering, or export behavior.

Code-Level Reference

For generated API documentation, see API Reference.