# nunomaduro/termwind architecture

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

- Interactive diagram: https://gitdiagram.com/nunomaduro/termwind
- Repository: https://github.com/nunomaduro/termwind

## Overview

##### Main Components
- User Application Code
– Invokes the global functions: render(), style(), ask(), terminal()
- Termwind Facade & Entry Point
– src/Functions.php: provides the public API
– src/Termwind.php: orchestrates the rendering pipeline
- Value Objects
– Node, Style, Styles (src/ValueObjects): represent parsed HTML elements and style definitions
- Component Definitions
– src/Components/* (Div, Span, Ul, Li, etc.): concrete element classes enforcing default styles and child restrictions
- Action Pipeline
– src/Actions/StyleToMethod.php: transforms Tailwind-style class strings into method calls or style applications
- HTML Rendering Subsystem
– src/HtmlRenderer.php: main renderer interface
– src/Html/PreRenderer.php, TableRenderer.php, CodeRenderer.php: specialized renderers for preformatted text, tables, code blocks
– src/Html/InheritStyles.php: handles style inheritance among nested nodes
- Style Repository & Configuration
– src/Repositories/Styles.php: stores default and custom style maps
– composer.json & phpstan.neon.dist: declare dependencies and configuration
- Interaction Helpers
– src/Helpers/QuestionHelper.php: prompts and reads user input for ask()
– src/Terminal.php: wraps low-level terminal operations (width, height, clear)
- Laravel Integration
– src/Laravel/TermwindServiceProvider.php: registers Termwind in Laravel’s service container
- Output Interface
– Direct STDOUT writes (no HTTP/web services)
– Optionally integrates with Symfony Console via QuestionHelper or Terminal class

##### Relationships & Data Flows
1. User code calls render()/ask()/style()/terminal()
2. Functions.php dispatches to Termwind or QuestionHelper or Style-related APIs
3. Termwind builds a tree of ValueObject Nodes and Styles, using
– Components to validate and wrap HTML elements
– Actions to parse “class” attributes into style rules
4. HtmlRenderer selects appropriate renderer (PreRenderer, TableRenderer, CodeRenderer, or default)
5. Renderer traverses the Node tree, applies Styles via Repositories, and issues ANSI-escaped output to STDOUT
6. Terminal may be consulted for sizing or clearing the screen
7. ask() uses QuestionHelper to render a prompt and read user input via STDIN
8. LaravelServiceProvider binds render() into Laravel’s command lifecycle

##### Architectural Patterns & Principles
- Facade Pattern: src/Functions.php hides underlying complexity
- Strategy Pattern: multiple renderer implementations selected at runtime
- Composition over Inheritance: HTML element classes compose ValueObject and style behavior
- Open/Closed Principle: style() lets users extend or override styles without modifying core code
- Single Responsibility: each folder (Components, Actions, Html, Repositories) has one clear concern

##### Extensibility & Integration Points
- Docker and CI directories (.github/workflows, docker/) as peripheral, non-runtime concerns

– Show only the most relevant classes or group them logically
– Emphasize that this is a library (no server or database components)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Code
    UserApp["User Application Code"]:::external

    %% Public API
    subgraph "Public API" 
        Functions["Functions.php"]:::publicAPI
        TermwindCore["Termwind.php"]:::publicAPI
    end

    %% Domain Layer
    subgraph "Domain (ValueObjects & Components)"
        subgraph "ValueObjects"
            NodeVO["Node.php"]:::domain
            StyleVO["Style.php"]:::domain
            StylesVO["Styles.php"]:::domain
        end
        subgraph "Components"
            ElementBase["Element.php"]:::domain
            Anchor["Anchor.php"]:::domain
            BreakLine["BreakLine.php"]:::domain
            Div["Div.php"]:::domain
            Dd["Dd.php"]:::domain
            Dl["Dl.php"]:::domain
            Dt["Dt.php"]:::domain
            Hr["Hr.php"]:::domain
            Li["Li.php"]:::domain
            Ol["Ol.php"]:::domain
            Paragraph["Paragraph.php"]:::domain
            Raw["Raw.php"]:::domain
            Span["Span.php"]:::domain
            Ul["Ul.php"]:::domain
        end
    end

    %% Processing Layer
    subgraph "Processing"
        StyleToMethod["StyleToMethod.php"]:::processing
        subgraph "Html Rendering"
            HtmlRenderer["HtmlRenderer.php"]:::processing
            PreRenderer["PreRenderer.php"]:::processing
            TableRenderer["TableRenderer.php"]:::processing
            CodeRenderer["CodeRenderer.php"]:::processing
            InheritStyles["InheritStyles.php"]:::processing
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        StylesRepo["Styles.php"]:::infra
        QuestionHelper["QuestionHelper.php"]:::infra
        Terminal["Terminal.php"]:::infra
    end

    %% Integration Layer
    subgraph "Integration"
        LaravelProvider["TermwindServiceProvider.php"]:::integration
        ComposerConfig["composer.json"]:::integration
        StaticAnalysis["phpstan.neon.dist"]:::integration
    end

    %% External Systems
    STDOUT["STDOUT"]:::external
    STDIN["STDIN"]:::external
    LaravelConsole["Laravel Console"]:::integration

    %% Connections
    UserApp -->|"calls render()/ask()/style()/terminal()"| Functions
    Functions -->|"delegates to"| TermwindCore
    Functions -->|"delegates ask() to"| QuestionHelper
    Functions -->|"delegates terminal() to"| Terminal

    TermwindCore -->|"builds tree of"| NodeVO
    TermwindCore -->|uses| StyleVO
    TermwindCore -->|uses| StylesVO
    TermwindCore -->|"wraps elements via"| ElementBase
    TermwindCore -->|validates via| Components
    TermwindCore -->|"parses classes via"| StyleToMethod
    TermwindCore -->|"renders via"| HtmlRenderer

    HtmlRenderer -->|"selects"| PreRenderer
    HtmlRenderer -->|"selects"| TableRenderer
    HtmlRenderer -->|"selects"| CodeRenderer
    HtmlRenderer -->|"applies inheritance via"| InheritStyles
    HtmlRenderer -->|"looks up styles in"| StylesRepo
    HtmlRenderer -->|"writes ANSI to"| STDOUT

    QuestionHelper -->|"reads prompt from"| STDIN
    QuestionHelper -->|"writes prompt to"| STDOUT

    Terminal -->|"writes control sequences to"| STDOUT

    UserApp -->|"registers in Laravel"| LaravelProvider
    LaravelProvider -->|"binds into"| LaravelConsole

    %% Peripheral config
    %% composer.json and phpstan.neon.dist are non-runtime

    %% Click Events
    click Functions "https://github.com/nunomaduro/termwind/blob/2.x/src/Functions.php"
    click TermwindCore "https://github.com/nunomaduro/termwind/blob/2.x/src/Termwind.php"
    click NodeVO "https://github.com/nunomaduro/termwind/blob/2.x/src/ValueObjects/Node.php"
    click StyleVO "https://github.com/nunomaduro/termwind/blob/2.x/src/ValueObjects/Style.php"
    click StylesVO "https://github.com/nunomaduro/termwind/blob/2.x/src/ValueObjects/Styles.php"
    click Anchor "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Anchor.php"
    click BreakLine "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/BreakLine.php"
    click Div "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Div.php"
    click Dd "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Dd.php"
    click Dl "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Dl.php"
    click Dt "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Dt.php"
    click ElementBase "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Element.php"
    click Hr "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Hr.php"
    click Li "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Li.php"
    click Ol "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Ol.php"
    click Paragraph "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Paragraph.php"
    click Raw "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Raw.php"
    click Span "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Span.php"
    click Ul "https://github.com/nunomaduro/termwind/blob/2.x/src/Components/Ul.php"
    click StyleToMethod "https://github.com/nunomaduro/termwind/blob/2.x/src/Actions/StyleToMethod.php"
    click HtmlRenderer "https://github.com/nunomaduro/termwind/blob/2.x/src/HtmlRenderer.php"
    click PreRenderer "https://github.com/nunomaduro/termwind/blob/2.x/src/Html/PreRenderer.php"
    click TableRenderer "https://github.com/nunomaduro/termwind/blob/2.x/src/Html/TableRenderer.php"
    click CodeRenderer "https://github.com/nunomaduro/termwind/blob/2.x/src/Html/CodeRenderer.php"
    click InheritStyles "https://github.com/nunomaduro/termwind/blob/2.x/src/Html/InheritStyles.php"
    click StylesRepo "https://github.com/nunomaduro/termwind/blob/2.x/src/Repositories/Styles.php"
    click QuestionHelper "https://github.com/nunomaduro/termwind/blob/2.x/src/Helpers/QuestionHelper.php"
    click Terminal "https://github.com/nunomaduro/termwind/blob/2.x/src/Terminal.php"
    click LaravelProvider "https://github.com/nunomaduro/termwind/blob/2.x/src/Laravel/TermwindServiceProvider.php"
    click ComposerConfig "https://github.com/nunomaduro/termwind/blob/2.x/composer.json"
    click StaticAnalysis "https://github.com/nunomaduro/termwind/blob/2.x/phpstan.neon.dist"

    %% Styles
    classDef publicAPI fill:#cff,stroke:#069,stroke-width:2px
    classDef domain fill:#cfc,stroke:#080,stroke-width:1px
    classDef processing fill:#ffc,stroke:#fa0,stroke-width:1px
    classDef infra fill:#fc9,stroke:#f60,stroke-width:1px
    classDef integration fill:#eee,stroke:#999,stroke-width:1px
    classDef external fill:#fff,stroke:#333,stroke-dasharray: 2 2

    class UserApp,STDOUT,STDIN external
    class LaravelConsole integration
```
