# chriskiehl/gooey architecture

> Architecture diagram of the GitHub repository chriskiehl/gooey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chriskiehl/gooey
- Repository: https://github.com/chriskiehl/gooey

## Overview

##### Project Type and Purpose
- Gooey is a Python library/tool that wraps a console (`argparse`)‑based Python program in a graphical user interface using wxPython. It is not a web app or microservice; it’s a desktop GUI wrapper for CLI scripts.

##### High‑Level Architectural Components
a. Developer Script
- Your existing Python script, with an `@Gooey` decorator or `GooeyParser`.
b. Python Bindings Layer (`gooey/python_bindings`)
- Intercepts `argparse` declarations, converts them into a JSON “build config.”
- Exposes decorator, custom parser, control objects and schema definitions.
c. Gooey Core (“Build” Phase)
- Entry point (`gooey/__main__.py` or `@Gooey`).
- Processor (`gooey/gui/processor.py`) reads the JSON config.
- PubSub (`gooey/gui/pubsub.py`) dispatches build events.
d. GUI Bootstrap & Host
- Bootstrapper (`gooey/gui/bootstrap.py`) initializes wxPython app.
- Host (`gooey/gui/host.py`) manages window life‑cycle and subprocess execution.
e. GUI Application & Components
- Application controller (`gooey/gui/application/application.py`) orchestrates UI.
- Component library (`gooey/gui/components`, `/containers`, `/widgets`) provides panels, layouts, input widgets.
- Formatters, validators, state store, event handlers.
f. Runtime Subprocess
- Gooey spawns your original script as a subprocess (via `target` argument).
- Captures STDOUT/STDERR to display in console panel, parse progress.
g. Packaging & Distribution
- `setup.py`, PyPI distribution, PyInstaller specs in `docs/packaging`.

##### Relationships & Data Flow
1. User runs `python my_script.py`
→ the `@Gooey` decorator activates.
2. Bindings layer inspects `argparse` actions and builds a JSON representation.
→ passed to the GUI processor.
3. Bootstrap initializes wxPython, loads JSON, and builds the GUI component tree.
4. User interacts with the GUI (fills forms, clicks “Start”).
→ pubsub events update internal `state`.
5. GUI Host spawns a subprocess running the original script, injecting user inputs as CLI args.
→ captures output streams.
6. Processor parses output against `progress_regex`/`progress_expr`
→ updates progress bar.
7. On subprocess exit:
- GUI shows success or failure screen.
- Fires lifecycle events (`on_success`, `on_error`).
- Allows custom handlers to modify UI state for the next run.

##### Key Architectural Patterns & Principles
- **Decorator Pattern**: `@Gooey` wraps your `main()` function.
- **Publisher–Subscriber**: `pubsub.py` mediates UI events and state updates.
- **Model–View–Controller (MVC)**:
- Model = JSON configuration + `state` object
- View = wxPython widgets
- Controller = Application logic in `application.py` and `host.py`
- **Separation of Concerns**:
- Bindings layer purely generates config;
- GUI layer purely renders and controls runtime;
- Subprocess layer purely runs user code.
- **Extensibility Points**:
- Custom widgets via `components/widgets`;
- Internationalization via `languages/*.json`;
- Packaging hooks via `docs/packaging`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top: Developer Script
    DevScript["Developer Script<br/>(@Gooey Decorated CLI)"]:::developer

    %% Python Bindings Layer
    subgraph "Python Bindings Layer" 
        direction TB
        Decorator["gooey_decorator.py"]:::internal
        ParserBinding["gooey_parser.py"]:::internal
        ArgparseJSON["argparse_to_json.py"]:::internal
        ConfigGen["config_generator.py"]:::internal
        ControlMod["control.py"]:::internal
        ParamsMod["parameters.py"]:::internal
        SchemaMod["schema.py"]:::internal
    end

    %% Build Phase Core
    subgraph "Gooey Core (Build Phase)"
        direction TB
        EntryPoint["__main__.py"]:::internal
        Processor["processor.py"]:::internal
        PubSub["pubsub.py"]:::internal
    end

    %% GUI Bootstrap & Host
    subgraph "GUI Bootstrap & Host"
        direction TB
        Bootstrap["bootstrap.py"]:::internal
        Host["host.py"]:::internal
    end

    %% GUI Application & Components
    subgraph "GUI Application & Components"
        direction TB
        AppCtrl["application.py"]:::internal
        CompAgg["components.py"]:::internal
        subgraph "Component Library"
            direction TB
            Layouts["layouts.py"]:::internal
            Options["options.py"]:::internal
            Footer["footer.py"]:::internal
            Header["header.py"]:::internal
            Sidebar["sidebar.py"]:::internal
            Tabbar["tabbar.py"]:::internal
            Dialogs["dialogs.py"]:::internal
            Modals["modals.py"]:::internal
            Widgets["widgets/"]:::internal
            Containers["containers/"]:::internal
        end
        Formatters["formatters.py"]:::internal
        Validators["validators.py"]:::internal
        StateStore["state.py"]:::internal
        Events["events.py"]:::internal
        subgraph "Internationalization"
            I18nLoader["i18n.py"]:::internal
            I18nConfig["i18n_config.py"]:::internal
            LangFiles["languages/*.json"]:::internal
        end
    end

    %% Subprocess Runner
    subgraph "Runtime Subprocess"
        direction TB
        CLIHelper["cli.py"]:::internal
        SubprocessApp["Original Script"]:::subprocess
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        Setup["setup.py"]:::internal
        WinSpec["docs/packaging/build-win.spec"]:::internal
        OsxSpec["docs/packaging/build-osx.spec"]:::internal
    end

    %% Flows
    DevScript -->|"imports decorator"| Decorator
    DevScript -->|"defines parser"| ParserBinding
    Decorator -->|"intercepts argparse"| ArgparseJSON
    ArgparseJSON -->|"generates JSON config"| ConfigGen
    ConfigGen -->|JSON build config| Processor
    EntryPoint -->|invoked by CLI| Processor
    Processor -->|reads config| PubSub
    PubSub -->|dispatch events| Bootstrap
    Bootstrap -->|init wxPython| Host
    Host -->|load UI structure| AppCtrl
    AppCtrl -->|orchestrates| CompAgg
    CompAgg --> Layouts & Options & Footer & Header & Sidebar & Tabbar & Dialogs & Modals & Widgets & Containers
    AppCtrl -->|uses| Formatters
    AppCtrl -->|uses| Validators
    AppCtrl -->|manages| StateStore
    AppCtrl -->|registers| Events
    AppCtrl -->|loads| I18nLoader & I18nConfig & LangFiles
    AppCtrl -->|on Start| CLIHelper
    CLIHelper -->|spawn| SubprocessApp
    SubprocessApp -->|STDOUT/STDERR| Processor
    Processor -->|progress updates| AppCtrl
    SubprocessApp -->|exit code| AppCtrl

    %% Click Events
    click Decorator "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/gooey_decorator.py"
    click ParserBinding "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/gooey_parser.py"
    click ArgparseJSON "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/argparse_to_json.py"
    click ConfigGen "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/config_generator.py"
    click ControlMod "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/control.py"
    click ParamsMod "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/parameters.py"
    click SchemaMod "https://github.com/chriskiehl/gooey/blob/master/gooey/python_bindings/schema.py"
    click EntryPoint "https://github.com/chriskiehl/gooey/blob/master/gooey/__main__.py"
    click Processor "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/processor.py"
    click PubSub "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/pubsub.py"
    click Bootstrap "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/bootstrap.py"
    click Host "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/host.py"
    click AppCtrl "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/application/application.py"
    click CompAgg "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/application/components.py"
    click Layouts "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/layouts/layouts.py"
    click Options "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/options/options.py"
    click Footer "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/footer.py"
    click Header "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/header.py"
    click Sidebar "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/sidebar.py"
    click Tabbar "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/tabbar.py"
    click Dialogs "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/dialogs.py"
    click Modals "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/components/modals.py"
    click Widgets "https://github.com/chriskiehl/gooey/tree/master/gooey/gui/components/widgets/"
    click Containers "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/containers/application.py"
    click Formatters "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/formatters.py"
    click Validators "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/validators.py"
    click StateStore "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/state.py"
    click Events "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/events.py"
    click I18nLoader "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/lang/i18n.py"
    click I18nConfig "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/lang/i18n_config.py"
    click LangFiles "https://github.com/chriskiehl/gooey/blob/master/gooey/languages/*.json"
    click CLIHelper "https://github.com/chriskiehl/gooey/blob/master/gooey/gui/cli.py"
    click Setup "https://github.com/chriskiehl/gooey/blob/master/setup.py"
    click WinSpec "https://github.com/chriskiehl/gooey/blob/master/docs/packaging/build-win.spec"
    click OsxSpec "https://github.com/chriskiehl/gooey/blob/master/docs/packaging/build-osx.spec"

    %% Styles
    classDef developer fill:#d4f4dd,stroke:#3c8d0d,color:#000
    classDef internal fill:#d0e1f9,stroke:#265a88,color:#000
    classDef subprocess fill:#f9d0d0,stroke:#882626,color:#000
```
