# ellisdickinson46/random-generator architecture

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

- Interactive diagram: https://gitdiagram.com/ellisdickinson46/random-generator
- Repository: https://github.com/ellisdickinson46/random-generator

## Overview

##### Project type and purpose
- This is a single-binary, desktop GUI application written in Python (generator.pyw + editor.pyw).
- Purpose: allow users to pick random items from lists via a “spinning wheel” UI and edit configurations.

##### File structure
- Entry points:
- generator.pyw – main random picker UI
- editor.pyw    – configuration editor UI
- Core package (`core/`):
- Business logic (data.py, convert.py)
- Configuration management (configuration.py)
- Localization (locale_manager.py + assets/locales/*.po)
- Logging & errors (logger.py, errors.py)
- UI framework adapters & widgets (`core/ui/`)
- Static assets (`assets/`):
- Configuration files (`config/`):
- app_config.json, lists.json
- Vendored libraries (`libs/`):
- Third-party dependencies: aiofiles, darkdetect, logbook, playsound3, polib, pywinstyles, sv_ttk

##### README for technical stack
- Python ≥3.8
- GUI using Tkinter + Sun Valley themes (sv_ttk)
- Logging via Logbook
- Localization via GNU gettext (.po/.mo)

##### Components
a. Entry-point layer
─ generator UI
─ editor UI
b. Core application layer
─ UI framework & widgets
─ Business logic & data model
─ Configuration & file I/O
─ Logging & error handling
─ Locale management
c. Data layer
─ JSON config files
─ .po/.mo locale files
d. External/OS layer
─ File system
─ OS theme detection (darkdetect)
e. Vendored third-party libraries

##### Relationships & interactions
- Entry point → Core UI → Business logic → Data layer → File system
- Core UI calls theme manager (sv_ttk + darkdetect)
- Core logic calls logger (logbook)
- Locale manager loads .po/.mo files from assets

##### Architectural patterns & design principles
- Separation of concerns: UI vs. business logic vs. data
- Plugin-style vendoring of third-party libs
- MVC-ish: widgets/controllers (UI), core/data (model), entry scripts (view/controller)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry-Point Layer
    subgraph "Entry-Point Layer"
        G["generator.pyw"]:::entry
        E["editor.pyw"]:::entry
    end

    %% Core Application Layer
    subgraph "Core Application"
        subgraph "UI Framework & Widgets"
            UI["core/ui/"]:::ui
            BaseWindow["base_window.py"]:::ui
            ApplyTheme["apply_theme.py"]:::ui
            NSWindowStyle["nswindow_style.py"]:::ui
            WCAGContrast["wcag_contrast.py"]:::ui
            DictVar["tk_var/"]:::ui
            WidgetsPack["widgets/"]:::ui
        end
        subgraph "Business Logic & Data Model"
            Data["data.py"]:::logic
            Convert["convert.py"]:::logic
        end
        subgraph "Configuration & File I/O"
            Config["configuration.py"]:::logic
        end
        subgraph "Logging & Error Handling"
            Logger["logger.py"]:::logic
            Errors["errors.py"]:::logic
        end
        subgraph "Locale Management"
            LocaleMgr["locale_manager.py"]:::logic
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        JSONCfg["config/"]:::data
        POFiles["assets/locales/"]:::data
        Icons["assets/icons/"]:::data
        Sounds["assets/sounds/"]:::data
    end

    %% Vendored Libraries
    subgraph "Vendored Libraries"
        Aio["aiofiles"]:::vend
        Dark["darkdetect"]:::vend
        LogbookLib["logbook"]:::vend
        Play["playsound3"]:::vend
        PolibLib["polib"]:::vend
        Winstyles["pywinstyles"]:::vend
        SVTTK["sv_ttk"]:::vend
    end

    %% External/OS Layer
    subgraph "External/OS"
        FileSys["File System"]:::external
        OSTheme["OS Theme Detection"]:::external
    end

    %% Connections - Entry to Core UI
    G -->|launches UI| UI
    E -->|launches UI| UI

    %% Core UI to Core Logic
    UI -->|invokes| Data
    UI -->|invokes| Convert
    UI -->|loads| Config
    UI -->|logs via| Logger
    UI -->|handles errors| Errors
    UI -->|manages locale| LocaleMgr

    %% UI Theme & OS Theme
    ApplyTheme -->|uses| SVTTK
    ApplyTheme -->|uses| Dark
    NSWindowStyle -->|adapts| Winstyles
    LocaleMgr -->|loads resources via| PolibLib

    %% Logging
    Logger -->|backend| LogbookLib

    %% File I/O
    Config -->|reads/writes| JSONCfg
    Data -->|reads/writes| JSONCfg
    Config -->|async I/O| Aio

    %% Data Layer to FileSys
    JSONCfg -->|stored in| FileSys
    POFiles -->|stored in| FileSys
    Icons -->|stored in| FileSys
    Sounds -->|stored in| FileSys

    %% Vendored Sound
    UI -->|plays| Play

    %% External OS Theme node
    Dark -->|detects| OSTheme

    %% Styles
    classDef entry fill:#DDEBF7,stroke:#4F81BD,stroke-width:1px;
    classDef ui fill:#DDEBF7,stroke:#5B9BD5,stroke-width:1px;
    classDef logic fill:#E2EFDA,stroke:#70AD47,stroke-width:1px;
    classDef data fill:#FCE4D6,stroke:#ED7D31,stroke-width:1px;
    classDef vend fill:#F2F2F2,stroke:#808080,stroke-width:1px;
    classDef external fill:#F2F2F2,stroke:#A6A6A6,stroke-width:1px;

    %% Click Events
    click G "https://github.com/ellisdickinson46/random-generator/blob/master/generator.pyw"
    click E "https://github.com/ellisdickinson46/random-generator/blob/master/editor.pyw"
    click UI "https://github.com/ellisdickinson46/random-generator/tree/master/core/ui/"
    click BaseWindow "https://github.com/ellisdickinson46/random-generator/blob/master/core/ui/base_window.py"
    click ApplyTheme "https://github.com/ellisdickinson46/random-generator/blob/master/core/ui/apply_theme.py"
    click NSWindowStyle "https://github.com/ellisdickinson46/random-generator/blob/master/core/ui/nswindow_style.py"
    click WCAGContrast "https://github.com/ellisdickinson46/random-generator/blob/master/core/ui/wcag_contrast.py"
    click DictVar "https://github.com/ellisdickinson46/random-generator/tree/master/core/ui/tk_var/"
    click WidgetsPack "https://github.com/ellisdickinson46/random-generator/tree/master/core/ui/widgets/"
    click Data "https://github.com/ellisdickinson46/random-generator/blob/master/core/data.py"
    click Convert "https://github.com/ellisdickinson46/random-generator/blob/master/core/convert.py"
    click Config "https://github.com/ellisdickinson46/random-generator/blob/master/core/configuration.py"
    click Logger "https://github.com/ellisdickinson46/random-generator/blob/master/core/logger.py"
    click Errors "https://github.com/ellisdickinson46/random-generator/blob/master/core/errors.py"
    click LocaleMgr "https://github.com/ellisdickinson46/random-generator/blob/master/core/locale_manager.py"
    click JSONCfg "https://github.com/ellisdickinson46/random-generator/tree/master/config/"
    click POFiles "https://github.com/ellisdickinson46/random-generator/tree/master/assets/locales/"
    click Icons "https://github.com/ellisdickinson46/random-generator/tree/master/assets/icons/"
    click Sounds "https://github.com/ellisdickinson46/random-generator/tree/master/assets/sounds/"
    click Aio "https://github.com/ellisdickinson46/random-generator/tree/master/libs/aiofiles/"
    click Dark "https://github.com/ellisdickinson46/random-generator/tree/master/libs/darkdetect/"
    click LogbookLib "https://github.com/ellisdickinson46/random-generator/tree/master/libs/logbook/"
    click Play "https://github.com/ellisdickinson46/random-generator/tree/master/libs/playsound3/"
    click PolibLib "https://github.com/ellisdickinson46/random-generator/tree/master/libs/polib/"
    click Winstyles "https://github.com/ellisdickinson46/random-generator/tree/master/libs/pywinstyles/"
    click SVTTK "https://github.com/ellisdickinson46/random-generator/tree/master/libs/sv_ttk/"
```
