# paulledemon/pyuibuilder architecture

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

- Interactive diagram: https://gitdiagram.com/paulledemon/pyuibuilder
- Repository: https://github.com/paulledemon/pyuibuilder

## Overview

##### Project Type & Purpose
- PyUIBuilder is a **web-based, single-page React application** that lets users drag-and-drop UI widgets and outputs Python GUI code (Tkinter, CustomTkinter).
- There is no traditional backend service in this repo; all code generation happens in the client.

##### Top-Level Components
From the file tree, identify these major subsystems:
a. **UI Layer (src/components, src/sidebar, src/styles, public/)**
b. **Canvas & Drag-Drop Engine (src/canvas, FabricJS integration)**
c. **State Management (src/redux, src/contexts)**
d. **Code Generation Engine (src/codeEngine + src/frameworks)**
e. **Framework Plugins (src/frameworks/tkinter, src/frameworks/customtk)**
f. **Static Assets & Landing Pages (demos/, docs/, landingpages/)**
g. **Build & Deployment (webpack.config.js, tailwind.config.js, package.json)**

##### Relationships & Data Flows
- **User → UI Layer**: Users interact via React components (toolbars, sidebars, canvas).
- **UI Layer ↔ State Management**: React components dispatch actions to Redux and read from Contexts (fileUploadContext, resizeContext, etc.).
- **UI Layer → Canvas Engine**: Canvas modules (fabric.js) render and manage widget placement.
- **Canvas Engine → State**: Canvas events (drag, resize) update shared state.
- **UI Layer → Code Generation Engine**: On “Generate Code,” the current state/tree of widgets is passed to `src/codeEngine/utils.js`.
- **Code Engine → Framework Plugins**: The engine invokes code templates in `src/frameworks/<framework>/engine` and `componentCodes`.
- **Framework Plugins → Code Output**: Templates produce Python code strings and a downloadable ZIP or file.
- **UI Layer → Download**: The generated code is sent back to the browser for user download.
- **External Services**: Optional analytics script (env var `REACT_APP_ANALYTICS_SCRIPT_ID`), hosted docs site, GitHub Pages for landing pages.

##### Architectural Patterns & Principles
- **Component-Based UI** (React functional components + hooks).
- **Modular Plugin Architecture**: Each framework implements a uniform interface—constants, engine code, componentCodes, plugins.
- **Unidirectional Data Flow**: Redux + React Contexts enforce predictable state updates.
- **Separation of Concerns**:
- UI Rendering vs. Canvas Logic vs. Code Generation.
- Framework-specific code isolated under `src/frameworks`.

##### Detailed Component Breakdown
- UI Layer:
- src/components (cards, inputs, modals, video-popup)
- src/sidebar (pluginsContainer, treeview, uploads)
- src/styles (Tailwind CSS, index.css)
- public (index.html, manifest.json)
- Canvas Engine:
- src/canvas/* (canvas, toolbar, widgets, utils, FabricJS integration)
- State Management:
- src/redux/store.js + assetSlice
- src/contexts (fileUploadContext, resizeContext, widgetContext)
- Code Generation:
- src/codeEngine/utils.js
- src/frameworks/*/engine & componentCodes
- Framework Plugins:
- tkinter (engine, plugins, pythonWidgets)
- customtkinter (engine, plugins, sidebarWidgets)
- Deployment & Docs:
- webpack.config.js, postcss.config.js, tailwind.config.js
- docs/ (Jekyll assets, GitHub Pages)
- landingpages/ (marketing landing pages)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Browser
    Browser["User Browser"]:::external

    subgraph "Frontend Application"
        direction TB

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            ReactUI["React UI Components"]:::frontend
            SidebarUI["Sidebar Components"]:::frontend
            Styles["Global Styles (Tailwind CSS)"]:::frontend
            PublicAssets["Public Static Assets & HTML"]:::frontend
            EntryPoint["App Entry Point (src/index.js, src/App.js)"]:::frontend
        end

        %% State Management
        subgraph "State Management"
            direction TB
            ReduxStore["Redux Store"]:::state
            AssetSlice["Asset Slice"]:::state
            FileUploadCtx["FileUploadContext"]:::state
            ResizeCtx["ResizeContext"]:::state
            WidgetCtx["WidgetContext"]:::state
        end

        %% Canvas Engine
        subgraph "Canvas & Drag-Drop Engine"
            direction TB
            CanvasCore["FabricJS Canvas Engine"]:::frontend
            CanvasToolbar["Canvas Toolbar"]:::frontend
            CanvasWidgets["Canvas Widgets"]:::frontend
            CanvasUtils["Canvas Utils"]:::frontend
        end

        %% Code Generation
        subgraph "Code Generation Engine"
            direction TB
            CodeEngine["Code Generation Engine"]:::codegen
            FrameworkUtils["Framework Utilities"]:::codegen
        end
    end

    %% Framework Plugins
    subgraph "Framework Plugins"
        direction TB
        subgraph "Tkinter Plugin"
            direction TB
            TkinterEngine["Tkinter Engine"]:::codegen
            TkinterComponents["Tkinter Component Codes"]:::codegen
            TkinterWidgets["Tkinter Widgets & Plugins"]:::codegen
        end
        subgraph "CustomTkinter Plugin"
            direction TB
            CustomEngine["CustomTkinter Engine"]:::codegen
            CustomComponents["CustomTkinter Component Codes"]:::codegen
            CustomWidgets["CustomTkinter Widgets & Plugins"]:::codegen
        end
    end

    %% External Services & Hosting
    Analytics["Analytics Script"]:::external
    DocsSite["Documentation Site"]:::external
    Landing["Landing Pages"]:::external
    BuildConfig["Build & Deployment Configs"]:::external

    Download["Download Generated Code"]:::external

    %% Connections
    Browser --> ReactUI
    ReactUI -->|dispatch actions| ReduxStore
    ReactUI -->|reads state| ReduxStore
    ReactUI --> CanvasCore
    CanvasCore -->|updates| ReduxStore
    ReactUI --> CodeEngine
    CodeEngine --> TkinterEngine
    CodeEngine --> CustomEngine
    CodeEngine --> FrameworkUtils
    TkinterEngine --> TkinterComponents
    TkinterEngine --> TkinterWidgets
    CustomEngine --> CustomComponents
    CustomEngine --> CustomWidgets
    CodeEngine --> Download
    ReactUI --> Download
    Analytics --> ReactUI

    %% Click Events
    click ReactUI "https://github.com/paulledemon/pyuibuilder/tree/main/src/components/"
    click SidebarUI "https://github.com/paulledemon/pyuibuilder/tree/main/src/sidebar/"
    click Styles "https://github.com/paulledemon/pyuibuilder/blob/main/src/styles/index.css"
    click Styles "https://github.com/paulledemon/pyuibuilder/blob/main/src/styles/tailwind.css"
    click PublicAssets "https://github.com/paulledemon/pyuibuilder/blob/main/public/index.html"
    click PublicAssets "https://github.com/paulledemon/pyuibuilder/blob/main/public/manifest.json"
    click PublicAssets "https://github.com/paulledemon/pyuibuilder/blob/main/public/robots.txt"
    click EntryPoint "https://github.com/paulledemon/pyuibuilder/blob/main/src/index.js"
    click EntryPoint "https://github.com/paulledemon/pyuibuilder/blob/main/src/App.js"
    click ReduxStore "https://github.com/paulledemon/pyuibuilder/blob/main/src/redux/store.js"
    click AssetSlice "https://github.com/paulledemon/pyuibuilder/blob/main/src/redux/assetSlice.js"
    click FileUploadCtx "https://github.com/paulledemon/pyuibuilder/blob/main/src/contexts/fileUploadContext.js"
    click ResizeCtx "https://github.com/paulledemon/pyuibuilder/blob/main/src/contexts/resizeContext.js"
    click WidgetCtx "https://github.com/paulledemon/pyuibuilder/blob/main/src/contexts/widgetContext.js"
    click CanvasCore "https://github.com/paulledemon/pyuibuilder/blob/main/src/canvas/canvas.js"
    click CanvasToolbar "https://github.com/paulledemon/pyuibuilder/blob/main/src/canvas/toolbar.js"
    click CanvasWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/canvas/widgets/"
    click CanvasUtils "https://github.com/paulledemon/pyuibuilder/blob/main/src/canvas/utils/utils.js"
    click TkinterEngine "https://github.com/paulledemon/pyuibuilder/blob/main/src/frameworks/tkinter/engine/code.js"
    click TkinterComponents "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/tkinter/engine/componentCodes/"
    click TkinterWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/tkinter/widgets/"
    click TkinterWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/tkinter/plugins/"
    click TkinterWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/tkinter/pythonWidgets/"
    click CustomEngine "https://github.com/paulledemon/pyuibuilder/blob/main/src/frameworks/customtk/engine/code.js"
    click CustomComponents "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/customtk/engine/componentCodes/"
    click CustomWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/customtk/widgets/"
    click CustomWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/customtk/plugins/"
    click CustomWidgets "https://github.com/paulledemon/pyuibuilder/tree/main/src/frameworks/customtk/assets/widgets/"
    click FrameworkUtils "https://github.com/paulledemon/pyuibuilder/blob/main/src/frameworks/utils/pythonFilePath.js"
    click Analytics "https://github.com/paulledemon/pyuibuilder/tree/main/env var REACT_APP_ANALYTICS_SCRIPT_ID"
    click DocsSite "https://github.com/paulledemon/pyuibuilder/blob/main/docs/index.html"
    click Landing "https://github.com/paulledemon/pyuibuilder/tree/main/landingpages/landingpage/"
    click Landing "https://github.com/paulledemon/pyuibuilder/tree/main/landingpages/buildinpublic/"
    click BuildConfig "https://github.com/paulledemon/pyuibuilder/blob/main/webpack.config.js"
    click BuildConfig "https://github.com/paulledemon/pyuibuilder/blob/main/tailwind.config.js"
    click BuildConfig "https://github.com/paulledemon/pyuibuilder/blob/main/postcss.config.js"
    click BuildConfig "https://github.com/paulledemon/pyuibuilder/blob/main/package.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef state fill:#E4F9E1,stroke:#28A745,color:#000
    classDef codegen fill:#FFE5B4,stroke:#FF8C00,color:#000
    classDef external fill:#F0F0F0,stroke:#666,color:#000
```
