# bashly-framework/bashly architecture

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

- Interactive diagram: https://gitdiagram.com/bashly-framework/bashly
- Repository: https://github.com/bashly-framework/bashly

## Overview

1. **What this repo is**
   Bashly is a Ruby-based CLI framework and generator whose primary output is a **single generated Bash script**. The Ruby app is the build-time engine; the generated Bash script is the runtime artifact used by end users.

2. **Top-level execution boundary**
   The main entrypoint is `bin/bashly`, which loads the Ruby library under `lib/bashly`. From there, the app exposes subcommands such as `init`, `generate`, `add`, `render`, `validate`, `doc`, `preview`, `shell`, and `completions`.

3. **Command-line application layer**
   `lib/bashly/cli.rb` and `lib/bashly/commands/*` define the user-facing tool behavior. This layer handles orchestration: parsing CLI arguments for Bashly itself, dispatching to a subcommand, and coordinating file I/O and output generation.

4. **Configuration input model**
   Bashly is driven by YAML config files, with schema definitions under `schemas/` and templates under `lib/bashly/templates/`. The key inputs are the CLI spec file (`bashly.yml`), optional settings, and optional strings/override files. These define commands, subcommands, flags, arguments, env vars, and doc output.

5. **Domain model for generated scripts**
   The `lib/bashly/script/` directory contains the internal representation of the target Bash program: commands, flags, arguments, dependencies, environment variables, variables, catch-alls, and wrappers. This is the core abstraction layer that turns YAML configuration into a structured script model.

6. **Validation and introspection**
   The `script/introspection/` and `config_validator.rb` code enforce structural rules before generation. This is where Bashly checks things like uniqueness, required fields, flag/argument constraints, command naming, and visibility/private/public behavior so invalid CLIs fail early.

7. **Rendering pipeline**
   The generation step uses a template/rendering system under `lib/bashly/views/` and `lib/bashly/render_context.rb` / `render_source.rb`. The views are `.gtx` templates for assembling the final Bash script sections: wrapper, parsing, usage text, command dispatch, validations, hooks, and helpers. This is the main transformation boundary from model to output.

8. **Generated script composition**
   The script output is intentionally modular before being flattened into one file. The views include reusable pieces for command filtering, arg parsing, help text, global flags, initialization hooks, and command bodies. That design makes the final script standalone while keeping generation maintainable in Ruby.

9. **Optional framework-style libraries**
   `lib/bashly/libraries/` contains built-in reusable assets that can be injected into generated CLIs, such as:
   - completions support
   - colors
   - INI/config management
   - YAML helpers
   - stacktrace handling
   - validations
   - hooks
   These are treated as reusable bundled features rather than part of the core parser.

10. **Docs, completion, and auxiliary outputs**
   Bashly also generates supporting artifacts: shell completions, Markdown/manpage docs, and example command/help output. The render-specific libraries under `lib/bashly/libraries/render/` and the docs templates under `lib/bashly/docs/` support these secondary outputs.

11. **Examples as architectural contracts**
   The large `examples/` tree is not just samples; it documents supported shapes of the configuration and generated script behavior. Each example is a small end-to-end workspace with its own `src/bashly.yml`, command files, optional libs/settings, and test script, showing how the generator behaves across features.

12. **Test strategy**
   `spec/approvals/` captures approved outputs for generated scripts, docs, and examples, while `spec/bashly/` contains unit and integration coverage for the Ruby generator itself. This strongly suggests the repo is validated by output comparison, not only by internal unit tests.

13. **Distribution and packaging**
   The project is published as a Ruby gem and also packaged as a Docker image. That means the generator is meant to run both in a local Ruby environment and in containerized CI/tooling workflows, but the architecture remains centered on “Ruby generator -> Bash output.”

14. **Overall data flow**
   The main flow is: user config files and command source files go into the Ruby generator, the config is validated and converted into an internal script model, templates render the model into a standalone Bash script, and optional docs/completions/support files are emitted alongside it.

Main entry points: [`lib/bashly/views`](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views) (Views), [`lib/bashly/config.rb`](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/config.rb) (Config), [`lib/bashly/script`](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/script) (Script model), [`spec/bashly`](https://github.com/bashly-framework/bashly/tree/master/spec/bashly) (Ruby specs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_cli["CLI app"]
  node_n_bin["bin/bashly<br/>entrypoint"]
  node_n_cli["CLI<br/>dispatcher<br/>[cli.rb]"]
  node_n_cmds["Commands"]
end

subgraph group_g_core["Core model"]
  node_n_config["Config<br/>input model<br/>[config.rb]"]
  node_n_schema["Schemas<br/>input schema<br/>[bashly.json]"]
  node_n_validator["Validator<br/>rules engine"]
  node_n_script["Script model<br/>domain model"]
  node_n_introspection["Introspection<br/>analysis"]
end

subgraph group_g_render["Rendering"]
  node_n_views["Views<br/>template set"]
  node_n_render_context["Render ctx<br/>context<br/>[render_context.rb]"]
  node_n_render_source["Render source<br/>source adapter<br/>[render_source.rb]"]
  node_n_wrapper["Wrapper<br/>output section"]
  node_n_command_views["Command views<br/>output section"]
  node_n_doc_views["Doc views<br/>output section"]
end

subgraph group_g_libs["Bundled libraries"]
  node_n_libs_base[("Built-ins<br/>assets")]
  node_n_libs_render["Render libs<br/>doc generators"]
end

subgraph group_g_quality["Examples & tests"]
  node_n_examples["Examples<br/>workspaces"]
  node_n_spec_approvals["Approvals<br/>golden outputs"]
  node_n_spec_unit["Ruby specs<br/>tests"]
end

node_n_bin -->|"boots"| node_n_cli
node_n_cli -->|"dispatches"| node_n_cmds
node_n_cmds -->|"loads"| node_n_config
node_n_config -->|"validates against"| node_n_schema
node_n_config -->|"checks"| node_n_validator
node_n_validator -->|"builds"| node_n_script
node_n_script -->|"analyzed by"| node_n_introspection
node_n_introspection -.->|"feeds rules"| node_n_validator
node_n_script -->|"renders with"| node_n_render_context
node_n_render_context -->|"sources"| node_n_render_source
node_n_render_context -->|"drives"| node_n_views
node_n_views -->|"includes"| node_n_wrapper
node_n_views -->|"includes"| node_n_command_views
node_n_views -->|"includes"| node_n_doc_views
node_n_libs_base -->|"injects"| node_n_script
node_n_libs_render -->|"supports"| node_n_doc_views
node_n_examples -.->|"demonstrates"| node_n_config
node_n_spec_approvals -.->|"verifies"| node_n_views
node_n_spec_approvals -.->|"captures"| node_n_examples
node_n_spec_unit -.->|"tests"| node_n_cli
node_n_spec_unit -.->|"tests"| node_n_config
node_n_spec_unit -.->|"tests"| node_n_script
node_n_spec_unit -.->|"tests"| node_n_views

click node_n_bin "https://github.com/bashly-framework/bashly/tree/master/bin/bashly"
click node_n_cli "https://github.com/bashly-framework/bashly/blob/master/lib/bashly/cli.rb"
click node_n_cmds "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/commands"
click node_n_config "https://github.com/bashly-framework/bashly/blob/master/lib/bashly/config.rb"
click node_n_schema "https://github.com/bashly-framework/bashly/blob/master/schemas/bashly.json"
click node_n_validator "https://github.com/bashly-framework/bashly/blob/master/lib/bashly/config_validator.rb"
click node_n_script "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/script"
click node_n_introspection "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/script/introspection"
click node_n_views "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views"
click node_n_render_context "https://github.com/bashly-framework/bashly/blob/master/lib/bashly/render_context.rb"
click node_n_render_source "https://github.com/bashly-framework/bashly/blob/master/lib/bashly/render_source.rb"
click node_n_wrapper "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views/wrapper"
click node_n_command_views "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views/command"
click node_n_doc_views "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries/render"
click node_n_libs_base "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries"
click node_n_libs_render "https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries/render"
click node_n_examples "https://github.com/bashly-framework/bashly/tree/master/examples"
click node_n_spec_approvals "https://github.com/bashly-framework/bashly/tree/master/spec/approvals"
click node_n_spec_unit "https://github.com/bashly-framework/bashly/tree/master/spec/bashly"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_bin,node_n_cli,node_n_cmds toneBlue
class node_n_config,node_n_schema,node_n_validator,node_n_script,node_n_introspection toneAmber
class node_n_views,node_n_render_context,node_n_render_source,node_n_wrapper,node_n_command_views,node_n_doc_views toneMint
class node_n_libs_base,node_n_libs_render toneRose
class node_n_examples,node_n_spec_approvals,node_n_spec_unit toneIndigo
```

## Components

### CLI app

Ruby entrypoint and command dispatch layer.

- [bin/bashly](https://github.com/bashly-framework/bashly/tree/master/bin/bashly): entrypoint · Executable that boots the Ruby CLI. · `bin/bashly`
- [CLI](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/cli.rb): dispatcher · Top-level application orchestration and subcommand routing. · `lib/bashly/cli.rb`
- [Commands](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/commands): subcommands · User-facing actions like init, generate, add, render, validate, doc, preview, shell, and completions. · `lib/bashly/commands`

### Core model

Configuration loading, validation, and script domain objects.

- [Config](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/config.rb): input model · Loads and represents Bashly YAML and settings inputs. · `lib/bashly/config.rb`
- [Schemas](https://github.com/bashly-framework/bashly/blob/master/schemas/bashly.json): input schema · JSON schema definitions for config, settings, and strings. · `schemas/bashly.json`
- [Validator](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/config_validator.rb): rules engine · Checks config structure, names, flags, args, visibility, and other constraints. · `lib/bashly/config_validator.rb`
- [Script model](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/script): domain model · Internal representation of the generated Bash program. · `lib/bashly/script`
- [Introspection](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/script/introspection): analysis · Derives command, flag, argument, dependency, and visibility metadata from the script model. · `lib/bashly/script/introspection`

### Rendering

Template-based transformation from model to generated Bash and docs.

- [Views](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views): template set · GTX templates that assemble script sections and helper fragments. · `lib/bashly/views`
- [Render ctx](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/render_context.rb): context · Holds rendering state and source mappings during generation. · `lib/bashly/render_context.rb`
- [Render source](https://github.com/bashly-framework/bashly/blob/master/lib/bashly/render_source.rb): source adapter · Represents renderable input sources for templates and docs. · `lib/bashly/render_source.rb`
- [Wrapper](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views/wrapper): output section · Generated script header and runtime bootstrap layer. · `lib/bashly/views/wrapper`
- [Command views](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/views/command): output section · Parsing, dispatch, usage, validation, hooks, and command-body templates. · `lib/bashly/views/command`
- [Doc views](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries/render): output section · Templates for Markdown and manpage-style documentation. · `lib/bashly/libraries/render`

### Bundled libraries

Reusable assets injected into generated scripts or auxiliary outputs.

- [Built-ins](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries): assets · Core reusable bundled assets such as colors, config, help, hooks, ini, stacktrace, validations, and yaml. · `lib/bashly/libraries`
- [Render libs](https://github.com/bashly-framework/bashly/tree/master/lib/bashly/libraries/render): doc generators · Bundled render targets for documentation output formats. · `lib/bashly/libraries/render`

### Examples & tests

Example workspaces and approval-based validation of generated output.

- [Examples](https://github.com/bashly-framework/bashly/tree/master/examples): workspaces · End-to-end sample workspaces that exercise supported configuration and generation patterns. · `examples`
- [Approvals](https://github.com/bashly-framework/bashly/tree/master/spec/approvals): golden outputs · Approved generated outputs for scripts, docs, completions, and examples. · `spec/approvals`
- [Ruby specs](https://github.com/bashly-framework/bashly/tree/master/spec/bashly): tests · Unit and integration coverage for the generator and its subsystems. · `spec/bashly`

## Connections

- bin/bashly → CLI: boots · Executable starts the Ruby application.
- CLI → Commands: dispatches · Routes arguments into subcommand handlers.
- Commands → Config: loads · Commands read config and settings inputs.
- Config → Schemas: validates against · Configuration structure is checked against schemas.
- Config → Validator: checks · Config is normalized and validated before generation.
- Validator → Script model: builds · Valid config is converted into the script domain model.
- Script model → Introspection: analyzed by · Introspection derives script metadata and constraints.
- Introspection → Validator: feeds rules · Derived metadata informs validation decisions.
- Script model → Render ctx: renders with · Model data is passed into the rendering context.
- Render ctx → Render source: sources · Context tracks the source objects being rendered.
- Render ctx → Views: drives · Templates are selected and rendered through context.
- Views → Wrapper: includes · Wrapper templates produce the Bash bootstrap section.
- Views → Command views: includes · Command templates produce parsing and dispatch sections.
- Views → Doc views: includes · Doc-related templates emit markdown and manpage output.
- Built-ins → Script model: injects · Bundled libraries become available to generated scripts.
- Render libs → Doc views: supports · Render libraries back secondary documentation output.
- Examples → Config: demonstrates · Example workspaces model supported config shapes and features.
- Approvals → Views: verifies · Golden outputs lock template rendering behavior.
- Approvals → Examples: captures · Approved outputs cover example workspaces and workflows.
- Ruby specs → CLI: tests · Specs cover CLI orchestration and command behavior.
- Ruby specs → Config: tests · Specs cover config loading and validation.
- Ruby specs → Script model: tests · Specs cover script model and introspection behavior.
- Ruby specs → Views: tests · Specs cover rendering templates and output assembly.