# jaykv/cliffy architecture

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

- Interactive diagram: https://gitdiagram.com/jaykv/cliffy
- Repository: https://github.com/jaykv/cliffy

## Overview

##### Main Components

a) Core Processing Components:
- Manifest Parser (parser.py)
- CLI Builder (builder.py)
- Command Manager (commander.py)
- Manifest Merger (merger.py)
- Code Transformer (transformer.py)

b) Commander Implementations:
- Click Commander
- Typer Commander

c) External Dependencies:
- Typer (Main CLI framework)
- Rich (Optional for formatting)
- PyBash (For subprocess calls)
- Shiv (For building zipapps)

**┌─ Input Layer ─────────────────┐**
- YAML Manifests               │
- CLI Definitions            │
- Command Configurations     │
- ┬───────────────┘
- ↓
**┌─ Core Processing Layer ───────┐**
- ┌─ Parser ─┐    ┌─ Merger ─┐ │
- YAML to  │←→  │ Combine  │ │
- Objects  │    │Manifests │ │
- ┬─────┘    └────────┬─┘ │
- ↓                   ↓    │
- ┌─ Builder ──────────────┐   │
- Generate CLI Structure │   │
- ┬───────────┘   │
- ↓               │
- ┌─ Commander ─────────────┐  │
- ┌─────────┐ ┌────────┐ │  │
- Typer   │ │ Click  │ │  │
- Commander│ │Commander│ │  │
- ┘ └────────┘ │  │
- ┬─┘  │
- ┬───────────────┘
- ↓
**┌─ Output Layer ────────────────┐**
- ┌─ Generated CLI ───────────┐│
- Python Scripts           ││
- Portable Zipapps        ││
- ┬─┘│
- ┘

##### Important Elements to Highlight

a) Development Flow:
- Hot-reload capability (reloader.py)
- Testing components (tester.py)
- Build process flow

b) Integration Points:
- How PyBash integrates for shell commands
- Jinja2 template processing
- Package management integration

##### Implementation Details

- The manifest-driven architecture
- The plugin-style commander system
- The transformation pipeline from YAML to executable CLI
- The build system for creating portable applications

##### Key Relationships

- How the manifest loader (loader.py) interacts with the parser
- How the transformer processes different command types
- Relationship between commanders and the generated CLI
- How the builder integrates with external packaging tools

- Nested components and layers
- Export to common formats (SVG, PNG)
- Easy updates for future modifications

Remember to maintain a balance between detail and clarity, focusing on the core architectural components while providing enough detail to understand the system's operation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef input fill:#a8d1f0,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef commander fill:#DDA0DD,stroke:#000
    classDef external fill:#FFA07A,stroke:#000
    classDef output fill:#a8d1f0,stroke:#000

    %% Input Layer
    subgraph Input
        YAML["YAML Manifests"]
        ManifestDefs["Manifest Definitions"]
    end
    click YAML "https://github.com/jaykv/cliffy/blob/main/examples/*.yaml"
    click ManifestDefs "https://github.com/jaykv/cliffy/blob/main/cliffy/manifests/v1.py"

    %% Core Processing Layer
    subgraph CoreProcessing
        subgraph ParsingLayer
            Parser["Manifest Parser"]
            Loader["Manifest Loader"]
            Merger["Manifest Merger"]
        end

        subgraph BuildLayer
            Builder["CLI Builder"]
            Transformer["Code Transformer"]
        end

        subgraph CommandLayer
            Commander["Command Manager"]
            ClickCmd["Click Commander"]
            TyperCmd["Typer Commander"]
        end

        subgraph DevTools
            Reloader["Hot Reloader"]
            Tester["Testing System"]
            RichFormat["Rich Formatting"]
        end
    end

    %% External Dependencies
    subgraph Dependencies
        Typer["Typer Framework"]
        Rich["Rich Library"]
        PyBash["PyBash"]
        Shiv["Shiv Builder"]
    end

    %% Output Layer
    subgraph Output
        CLI["Main CLI Interface"]
        Generated["Generated CLIs"]
    end

    %% Component Mappings
    click Parser "https://github.com/jaykv/cliffy/blob/main/cliffy/parser.py"
    click Builder "https://github.com/jaykv/cliffy/blob/main/cliffy/builder.py"
    click Commander "https://github.com/jaykv/cliffy/blob/main/cliffy/commander.py"
    click Merger "https://github.com/jaykv/cliffy/blob/main/cliffy/merger.py"
    click Transformer "https://github.com/jaykv/cliffy/blob/main/cliffy/transformer.py"
    click ClickCmd "https://github.com/jaykv/cliffy/blob/main/cliffy/commanders/click.py"
    click TyperCmd "https://github.com/jaykv/cliffy/blob/main/cliffy/commanders/typer.py"
    click Loader "https://github.com/jaykv/cliffy/blob/main/cliffy/loader.py"
    click Reloader "https://github.com/jaykv/cliffy/blob/main/cliffy/reloader.py"
    click Tester "https://github.com/jaykv/cliffy/blob/main/cliffy/tester.py"
    click RichFormat "https://github.com/jaykv/cliffy/blob/main/cliffy/rich.py"
    click CLI "https://github.com/jaykv/cliffy/blob/main/cliffy/cli.py"
    click Generated "https://github.com/jaykv/cliffy/tree/main/examples/generated/"

    %% Relationships
    YAML --> Loader
    ManifestDefs --> Parser
    Loader --> Parser
    Parser --> Merger
    Merger --> Builder
    Builder --> Transformer
    Transformer --> Commander
    Commander --> ClickCmd & TyperCmd
    ClickCmd & TyperCmd --> CLI
    CLI --> Generated

    %% Development Tools Connections
    Reloader -.-> Parser
    Tester -.-> Generated
    RichFormat -.-> CLI

    %% External Dependencies
    Typer -.-> TyperCmd
    Rich -.-> RichFormat
    PyBash -.-> CLI
    Shiv -.-> Generated

    %% Styling Classes
    class YAML,ManifestDefs input
    class Parser,Loader,Merger,Builder,Transformer,Commander,Reloader,Tester,RichFormat core
    class ClickCmd,TyperCmd commander
    class Typer,Rich,PyBash,Shiv external
    class CLI,Generated output
```
