# peterbrittain/asciimatics architecture

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

- Interactive diagram: https://gitdiagram.com/peterbrittain/asciimatics
- Repository: https://github.com/peterbrittain/asciimatics

## Overview

##### Project type and purpose
- This is a Python library (open-source toolkit) named “Asciimatics” for building full-screen text UIs and ASCII animations on multiple platforms.

##### File structure
- Top-level package “asciimatics/” contains the core code:
- constants.py, utilities.py, exceptions.py, event.py, parsers.py, particles.py, paths.py
- screen.py (terminal abstraction), scene.py (scene manager), effects.py (animation primitives)
- Sub-packages:
- renderers/ — pluggable renderers (text, images, charts, fire, etc.)
- Support directories:
- samples/ — example scripts showing usage
- tests/ — unit tests for every module
- doc/ — Sphinx-based documentation
- CI, linting, packaging files (.github/, setup.py, requirements/).

##### Insights from README
- Core concepts: Screen wrapper → Scene → Effects → Renderers → low-level console APIs.
- Provides both low-level APIs (direct printing, input capture) and high-level APIs (widgets, animations).
- Cross-platform via curses or Windows console APIs, with backends hidden behind Screen class.

##### Elements
- “init & refresh cycle” from Screen to Terminal Backend
- “publish events” from Terminal Backend to Screen to Scene/Widgets
- “frame data” from Renderers to Screen
- “run effect” from Scene Manager to Effects
- blue for core abstractions,
- green for high-level modules (Effects, Widgets),
- gray for backend & external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Code / Application"]:::client
    click Client "https://github.com/peterbrittain/asciimatics/tree/master/samples/"

    %% Extension Layer
    subgraph "High-Level Extensions"
        Effects["Effects Engine"]:::ext
        click Effects "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/effects.py"
        Renderers["Renderers"]:::ext
        click Renderers "https://github.com/peterbrittain/asciimatics/tree/master/asciimatics/renderers/"
        Widgets["Widget Framework"]:::ext
        click Widgets "https://github.com/peterbrittain/asciimatics/tree/master/asciimatics/widgets/"
    end

    %% Core Layer
    subgraph "Core Abstractions"
        Screen["Screen (core abstraction)"]:::core
        click Screen "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/screen.py"
        Scene["Scene Manager"]:::core
        click Scene "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/scene.py"
        Events["Event System"]:::core
        click Events "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/event.py"
        Exceptions["Exceptions Module"]:::core
        click Exceptions "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/exceptions.py"
        subgraph "Utilities & Parsers"
            Utilities["Utilities"]:::core
            click Utilities "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/utilities.py"
            Parsers["Parsers"]:::core
            click Parsers "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/parsers.py"
            Constants["Constants"]:::core
            click Constants "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/constants.py"
            Particles["Particles"]:::core
            click Particles "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/particles.py"
            Paths["Paths"]:::core
            click Paths "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/paths.py"
        end
    end

    %% Backend & External
    subgraph "Backend & External"
        Backend["Terminal Backend"]:::backend
        click Backend "https://github.com/peterbrittain/asciimatics/blob/master/asciimatics/screen.py"
        External["External Dependencies"]:::backend
    end

    %% Connections
    Client -->|"calls wrapper"| Screen
    Screen -->|"init & refresh cycle"| Backend
    Backend -->|"publish events"| Screen
    Screen -->|"reads events"| Events
    Events -->|"dispatch events"| Scene
    Events -->|"dispatch events"| Widgets
    Scene -->|"run effect"| Effects
    Effects -->|"use renderer"| Renderers
    Widgets -->|"use renderers"| Renderers
    Renderers -->|"frame data"| Screen
    Screen -->|"display frame"| Backend
    Utilities -.-> Screen
    Utilities -.-> Scene
    Utilities -.-> Effects
    Utilities -.-> Widgets
    Exceptions -.-> Screen
    Exceptions -.-> Scene
    Exceptions -.-> Effects
    Exceptions -.-> Renderers
    Exceptions -.-> Widgets

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef ext fill:#afa,stroke:#333,stroke-width:1px
    classDef core fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#eee,stroke:#333,stroke-width:1px
```
