# ninostephen/durdraw architecture

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

- Interactive diagram: https://gitdiagram.com/ninostephen/durdraw
- Repository: https://github.com/ninostephen/durdraw

## Overview

##### Project type and purpose
- Durdraw is a terminal-based ASCII/Unicode/ANSI art editor and animation tool written in Python. It provides:
- An interactive TUI editor (uses curses)
- Command-line playback/export tools (`durdraw`, `durfetch`, `durview`)
- A plugin subsystem for frame-based animations and charset conversions
- Configuration via INI files and built-in themes/charsets

##### File structure
- Top-level executables and scripts:
- `durdraw` (entry point CLI script)
- `durfetch` (CLI wrapper for Neofetch integration)
- `durview` (animation viewing CLI)
- `start-durdraw`, shebang convenience script
- Core package directory: `durdraw/`
- Submodules by feature:
– `durdraw_ansiparse.py`, `durdraw_file.py` (file I/O and parsing)
– `durdraw_appstate.py` (application state management)
– `durdraw_gui_manager*.py`, `durdraw_ui_*.py` (UI layer)
– `durdraw_undo.py` (undo/redo subsystem)
– `durdraw_plugins/` (animation and charset plugins)
– `durdraw_charsets.py`, `charsets/` (character set definitions)
– `durdraw_themes/` (theme definitions)
- Config and metadata:
- `durdraw.ini`, `pyproject.toml`, Dockerfile, install scripts
- Tests: `test/durdraw/`

##### README for additional insights
- Architecture is not explicitly diagrammed but key components and CLI commands are described
- External dependencies: Python 3, curses, optional `ansilove` (PNG/GIF export), `neofetch` (durfetch)

a. Main components:
1. CLI Frontend Layer
- Entry point scripts (`durdraw`, `durfetch`, `durview`)
- Argument parser and command dispatch
2. Core Engine
- Application State Manager (`durdraw_appstate.py`)
- Options & Config Loader (`durdraw_options.py`)
- Undo/Redo Manager (`durdraw_undo.py`)
3. File & Format Layer
- Parser/Serializer (`durdraw_ansiparse.py`, `durfile.py`)
- `.dur` JSON format (see `durformat.md`)
- ANSI/ASCII import/export
4. UI Layer (Terminal)
- Low-level curses interface (`durdraw_color_curses.py`)
- GUI Manager (`durdraw_gui_manager.py`, `durdraw_gui_manager_curses.py`)
- UI Widgets (`durdraw_ui_widgets.py`, `durdraw_ui_widgets_curses.py`)
- Input handling (keyboard, mouse)
5. Domain Services
- Character Sets & Themes (`durdraw_charsets.py`, `charsets/`, `themes/`)
- Animation Plugins (`plugins/*.py`)
- Durfetch integration (`durfetch.py`)
6. External Systems
- `ncurses` library
- `ansilove` (optional)
- `neofetch` (optional for `durfetch`)
- File system (read/write `.dur`, config, examples)
b. Relationships and interactions:
- CLI Frontend invokes Core Engine with parsed options
- Core Engine loads Config + Themes/Charsets
- Core Engine orchestrates File & Format Layer to load/save art
- Core Engine pushes drawing commands to UI Layer
- UI Layer renders frames and captures user input, then updates App State
- Plugins hook into the Core Engine for animation operations or charset conversion
- Durfetch wraps Core Engine + Plugins + external `neofetch`
c. Architectural patterns and design principles:
- Modular separation: CLI vs Core vs UI vs File/Format vs Domain Services
- Plugin architecture for extendibility (animation, charset conversion)
- MVC-like pattern:
- Model = AppState + Document (`durdraw_appstate.py` + file modules)
- View = UI Layer (curses GUI Manager + Widgets)
- Controller = Core Engine + Command dispatch + Input handlers
- Configuration-driven (INI files for themes, charsets, main options)
d. Key technologies & libraries:
- Python 3
- curses (ncurses/pdcurses) for TUI
- ConfigParser for INI files
- JSON for `.dur` format
- Optional: ansilove, neofetch

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: CLI Frontend Layer
    subgraph "CLI Frontend Layer"
        CLI_DUR["durdraw"]:::internal
        CLI_FETCH["durfetch"]:::internal
        CLI_VIEW["durview"]:::internal
        CLI_START["start-durdraw"]:::internal
    end

    %% Subgraph: Core Engine
    subgraph "Core Engine"
        APP_STATE["AppState Manager"]:::internal
        CONFIG_LOADER["Options & Config Loader"]:::internal
        UNDO_MANAGER["Undo/Redo Manager"]:::internal
        MAIN_ORCH["TUI Orchestrator"]:::internal
    end

    %% Subgraph: File & Format Layer
    subgraph "File & Format Layer"
        ANSI_PARSE["ANSI/ASCII Parser"]:::internal
        FILE_IO["File I/O & Serializer"]:::internal
        DUR_SPEC[".dur JSON Format Spec"]:::resource
    end

    %% Subgraph: UI Layer (Terminal)
    subgraph "UI Layer (Terminal)"
        COLOR_CURSES["Curses Color Mgmt"]:::internal
        GUI_MANAGER["GUI Manager (Generic)"]:::internal
        GUI_CURSES["GUI Manager (Curses)"]:::internal
        UI_WIDGETS["UI Widgets (Generic)"]:::internal
        WIDGETS_CURSES["UI Widgets (Curses)"]:::internal
        UI_CURSES["Curses Integration & Input"]:::internal
    end

    %% Subgraph: Domain Services
    subgraph "Domain Services"
        CHARSETS["Character Sets Manager"]:::internal
        CHARSETS_DIR["Built-in Charsets"]:::resource
        THEMES_DIR["Built-in Themes"]:::resource
        PLUGIN_BOUNCE["bounce_movie.py"]:::resource
        PLUGIN_CONVERT["convert_charset.py"]:::resource
        PLUGIN_REPEAT["repeat_movie.py"]:::resource
        PLUGIN_REVERSE["reverse_movie.py"]:::resource
    end

    %% Subgraph: Durfetch Integration Service
    subgraph "Durfetch Integration Service"
        DURFETCH_WRAPPER["durfetch.py"]:::internal
        NEOFETCHER["neofetcher.py"]:::internal
    end

    %% Subgraph: Help & Examples
    subgraph "Help & Examples"
        HELP_DIR["In-app Help"]:::resource
        DURF_DIR["Example .dur Files"]:::resource
        EXAMPLES["examples/"]:::resource
    end

    %% Subgraph: Metadata & Configuration
    subgraph "Metadata & Configuration"
        INI_CONF["durdraw.ini"]:::resource
        PYPROJECT["pyproject.toml"]:::resource
        MAN_DUR["durdraw.1"]:::resource
        MAN_FETCH["durfetch.1"]:::resource
        MAN_VIEW["durview.1"]:::resource
    end

    %% External Dependencies
    subgraph "External Dependencies"
        NCURSES["ncurses"]:::external
        ANSILOVE["ansilove (optional)"]:::external
        NEOFETCH["neofetch (optional)"]:::external
        FILESYS["File System"]:::external
    end

    %% Connections
    CLI_DUR -->|"invoke"| MAIN_ORCH
    CLI_VIEW -->|"invoke"| MAIN_ORCH
    CLI_FETCH -->|"invoke"| DURFETCH_WRAPPER
    CLI_START -->|"helper"| MAIN_ORCH

    MAIN_ORCH -->|"uses"| APP_STATE
    MAIN_ORCH -->|"loads"| CONFIG_LOADER
    MAIN_ORCH -->|"manages"| UNDO_MANAGER

    MAIN_ORCH -->|"read/write"| FILE_IO
    MAIN_ORCH -->|"parse"| ANSI_PARSE
    FILE_IO -->|".dur spec"| DUR_SPEC

    MAIN_ORCH -->|"push commands"| GUI_MANAGER
    GUI_MANAGER -->|"render"| GUI_CURSES
    GUI_CURSES -->|"color"| COLOR_CURSES
    GUI_CURSES -->|"widgets"| WIDGETS_CURSES
    GRAPH_UI_INPUT(UI_Input):::internal
    UI_CURSES -->|"capture input"| APP_STATE
    APP_STATE -->|"update view"| GUI_MANAGER

    MAIN_ORCH -->|"load resources"| CHARSETS
    CHARSETS -->|"dir"| CHARSETS_DIR
    MAIN_ORCH -->|"load themes"| THEMES_DIR

    MAIN_ORCH -->|"plugin hook"| PLUGIN_BOUNCE
    MAIN_ORCH -->|"plugin hook"| PLUGIN_CONVERT
    MAIN_ORCH -->|"plugin hook"| PLUGIN_REPEAT
    MAIN_ORCH -->|"plugin hook"| PLUGIN_REVERSE

    DURFETCH_WRAPPER -->|"calls"| NEOFETCHER
    NEOFETCHER -->|"executes"| NEOFETCH

    MAIN_ORCH -->|"read help"| HELP_DIR
    MAIN_ORCH -->|"load examples"| DURF_DIR
    MAIN_ORCH -->|"load examples"| EXAMPLES

    CONFIG_LOADER -->|"read"| INI_CONF
    CONFIG_LOADER -->|"read"| PYPROJECT
    CONFIG_LOADER -->|"load manpages"| MAN_DUR
    CONFIG_LOADER -->|"load manpages"| MAN_FETCH
    CONFIG_LOADER -->|"load manpages"| MAN_VIEW

    MAIN_ORCH -->|"read/write"| FILESYS
    ANSI_PARSE -->|"optional export"| ANSILOVE

    MAIN_ORCH -->|"link curses"| NCURSES

    %% Click Events
    click CLI_DUR "https://github.com/ninostephen/durdraw/tree/master/./durdraw"
    click CLI_FETCH "https://github.com/ninostephen/durdraw/tree/master/./durfetch"
    click CLI_VIEW "https://github.com/ninostephen/durdraw/tree/master/./durview"
    click CLI_START "https://github.com/ninostephen/durdraw/tree/master/./start-durdraw"
    click APP_STATE "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_appstate.py"
    click CONFIG_LOADER "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_options.py"
    click UNDO_MANAGER "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_undo.py"
    click MAIN_ORCH "https://github.com/ninostephen/durdraw/blob/master/durdraw/main.py"
    click ANSI_PARSE "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_ansiparse.py"
    click FILE_IO "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_file.py"
    click DUR_SPEC "https://github.com/ninostephen/durdraw/blob/master/durformat.md"
    click COLOR_CURSES "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_color_curses.py"
    click GUI_MANAGER "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_gui_manager.py"
    click GUI_CURSES "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_gui_manager_curses.py"
    click UI_WIDGETS "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_ui_widgets.py"
    click WIDGETS_CURSES "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_ui_widgets_curses.py"
    click UI_CURSES "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_ui_curses.py"
    click CHARSETS "https://github.com/ninostephen/durdraw/blob/master/durdraw/durdraw_charsets.py"
    click CHARSETS_DIR "https://github.com/ninostephen/durdraw/tree/master/durdraw/charsets/"
    click THEMES_DIR "https://github.com/ninostephen/durdraw/tree/master/durdraw/themes/"
    click PLUGIN_BOUNCE "https://github.com/ninostephen/durdraw/blob/master/durdraw/plugins/bounce_movie.py"
    click PLUGIN_CONVERT "https://github.com/ninostephen/durdraw/blob/master/durdraw/plugins/convert_charset.py"
    click PLUGIN_REPEAT "https://github.com/ninostephen/durdraw/blob/master/durdraw/plugins/repeat_movie.py"
    click PLUGIN_REVERSE "https://github.com/ninostephen/durdraw/blob/master/durdraw/plugins/reverse_movie.py"
    click DURFETCH_WRAPPER "https://github.com/ninostephen/durdraw/blob/master/durdraw/durfetch.py"
    click NEOFETCHER "https://github.com/ninostephen/durdraw/blob/master/durdraw/neofetcher.py"
    click HELP_DIR "https://github.com/ninostephen/durdraw/tree/master/durdraw/help/"
    click DURF_DIR "https://github.com/ninostephen/durdraw/tree/master/durdraw/durf/"
    click EXAMPLES "https://github.com/ninostephen/durdraw/tree/master/examples/"
    click INI_CONF "https://github.com/ninostephen/durdraw/blob/master/durdraw.ini"
    click PYPROJECT "https://github.com/ninostephen/durdraw/blob/master/pyproject.toml"
    click MAN_DUR "https://github.com/ninostephen/durdraw/blob/master/durdraw.1"
    click MAN_FETCH "https://github.com/ninostephen/durdraw/blob/master/durfetch.1"
    click MAN_VIEW "https://github.com/ninostephen/durdraw/blob/master/durview.1"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef resource fill:#FCF3CF,stroke:#F1C40F,stroke-width:1px
```
