# rzcastilho/do_it architecture

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

- Interactive diagram: https://gitdiagram.com/rzcastilho/do_it
- Repository: https://github.com/rzcastilho/do_it

## Overview

##### Project type and purpose
- Project type: An Elixir library to build CLI applications.
- Purpose: Provide a set of macros (`DoIt.MainCommand`, `DoIt.Command`) and runtime modules to parse arguments/options, dispatch commands, generate help/version, and support shell auto‐completion.
- Key indicators: `lib/do_it`, `mix/tasks`, `README` describes macros, commands, escript/burrito packaging, completion features.

A. Core Library (lib/do_it)
– DoIt.MainCommand (macro)
– DoIt.Command (macro)
– Runner
– Argument, Option, Command, Subcommand modules
– Completion engine (`DoIt.Completion`)
– Introspection, Helper, Output, Exceptions
– Configuration loader (`DoIt.Config`/mix config)
B. Mix Tasks (lib/mix/tasks)
– do_it.config.init
– do_it.gen.completion
C. Packaging & Build
– Escript (Mix’s escript.build using `:escript.main_module`)
– Burrito‐Elixir (releases + Burrito.wrap)
D. Example Client (examples/hello_world)
– Uses MainCommand/Command to define `HelloWorld` CLI
– Drives EEx templates, subcommands, options
E. External Dependencies & Services
– Elixir/Erlang runtime
– EEx template engine
– Shell environments (bash, fish, zsh) for completion scripts

1. Compile-time:
- User Client code → invokes `use DoIt.MainCommand` or `use DoIt.Command` macros → Macro expansion generates command modules, dispatch functions, help/version handlers.
- Mix tasks (`do_it.*`) integrate into `mix` CLI to scaffold config or generate completion scripts.
2. Runtime:
- User types `my_cli ...` in shell → escript/Burrito wrapper invokes `MainCommand.run(args)` (Runner).
- Runner parses args → matches command/subcommand → invokes corresponding `Command.run/3`.
- `DoIt.Argument` and `DoIt.Option` modules handle parsing & validation.
- `DoIt.Completion` handles special `completion` commands and generates shell scripts.
- `DoIt.Output` handles printing to STDOUT/STDERR.
- Config subsystem (`DoIt.Config`) loads default templates or settings from `config/*.exs` or user’s context.
- Errors and help are managed by `DoIt.Exceptions` and auto-generated help routines.

##### Architectural patterns
- Macro-based code generation at compile time (metaprogramming).
- Layered design: Parsing → Dispatch → Execution → Output.
- Plugin-style extensibility via macros: users “plug in” new commands or subcommands.
- Command pattern: each module encapsulates a single action.
- Single binary entrypoint (escript/burrito) feeding into a generic runner.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Library
    subgraph "Core Library"
        direction TB
        MC["DoIt.MainCommand (macro)"]:::core
        CMD["DoIt.Command (macro)"]:::core
        RUN["Runner"]:::core
        ARG["DoIt.Argument"]:::core
        OPT["DoIt.Option"]:::core
        COMP["DoIt.Completion"]:::core
        INT["DoIt.Introspection"]:::core
        HLP["DoIt.Helper"]:::core
        OUT["DoIt.Output"]:::core
        EXC["DoIt.Exceptions"]:::core
        CFG["DoIt.Config"]:::core
    end

    %% Mix Tasks
    subgraph "Mix Tasks"
        direction TB
        MT1["mix do_it.config.init"]:::build
        MT2["mix do_it.gen.completion"]:::build
    end

    %% Packaging & Build
    subgraph "Packaging & Build"
        direction TB
        PKG["mix.exs (escript & burrito)"]:::build
    end

    %% Example Client App
    subgraph "Example Client App"
        direction TB
        CB["HelloWorld CLI"]:::client
        CS1["say (subcommand)"]:::client
        CT["template"]:::client
        CTS["template/set"]:::client
        CTH["template/show"]:::client
        CTU["template/unset"]:::client
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        EXT1["Elixir/Erlang runtime"]:::external
        EXT2["EEx template engine"]:::external
        EXT3["Shell env (bash,fish,zsh)"]:::external
    end

    %% Compile-time relations
    CB -->|"use macros"| MC
    CB -->|"use macros"| CMD
    MC --> INT
    MC --> HLP
    CMD --> INT
    CMD --> HLP

    %% Mix integration
    MT1 -->|"scaffold config"| CFG
    MT2 -->|"generate scripts"| COMP

    %% Packaging flow
    PKG -->|"build binary"| RUN

    %% Runtime flow
    EXT3 -->|"invoke binary"| RUN
    RUN -->|"parse args"| ARG
    RUN -->|"parse options"| OPT
    RUN -->|"dispatch"| CMD
    RUN -->|"dispatch"| CB
    RUN -->|"handle completion"| COMP
    RUN -->|"load config"| CFG
    RUN -->|"output"| OUT
    RUN -->|"errors/help"| EXC

    CMD --> CS1
    CMD --> CT
    CT --> CTS
    CT --> CTH
    CT --> CTU

    %% External template usage
    CB -->|"render templates"| EXT2

    %% Click Events
    click MC "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/main_command.ex"
    click CMD "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/command.ex"
    click RUN "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/runner.ex"
    click ARG "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/argument.ex"
    click OPT "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/option.ex"
    click COMP "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/completion.ex"
    click INT "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/introspection.ex"
    click HLP "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/helper.ex"
    click OUT "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/output.ex"
    click EXC "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/exceptions.ex"
    click CFG "https://github.com/rzcastilho/do_it/blob/master/lib/do_it/commfig.ex"
    click MT1 "https://github.com/rzcastilho/do_it/blob/master/lib/mix/tasks/do_it.config.init.ex"
    click MT2 "https://github.com/rzcastilho/do_it/blob/master/lib/mix/tasks/do_it.gen.completion.ex"
    click PKG "https://github.com/rzcastilho/do_it/blob/master/mix.exs"
    click CB "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world.ex"
    click CS1 "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world/say.ex"
    click CT "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world/template.ex"
    click CTS "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world/template/set.ex"
    click CTH "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world/template/show.ex"
    click CTU "https://github.com/rzcastilho/do_it/blob/master/examples/hello_world/lib/hello_world/template/unset.ex"

    %% Styles
    classDef core fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef client fill:#c6e2f0,stroke:#333,stroke-width:1px
    classDef build fill:#f0d7a8,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
