# guardino/trova architecture

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

- Interactive diagram: https://gitdiagram.com/guardino/trova
- Repository: https://github.com/guardino/trova

## Overview

##### Project Type and Purpose
- This is an open-source suite of command-line utilities written in Perl.
- It contains four standalone scripts—trova.pl, confronta.pl, quale.pl, forte.pl—each providing a file-system or code-analysis function, plus a Windows build script (build.bat) to package them as executables.

##### Top-Level Components
- User (CLI)
- Perl Interpreter (runtime)
- Scripts (trova.pl, confronta.pl, quale.pl, forte.pl)
- Build Script (build.bat) / PAR-based packager
- File System (directories, files to search/compare)
- External Tools
- diff tool (for confronta.pl)
- Graphviz ‘dot’ (for forte.pl)
- OS PATH lookup (for quale.pl)

##### Interactions and Data Flows
- User invokes one of the scripts or the packaged .exe
→ Script parses arguments and options
→ Script invokes a directory/file walker (Perl’s File::Find or custom recursion)
→ Script applies regex filters or patterns to file names or contents
→ Based on flags, script may
– Print matches or counts
– Rename, delete, or substitute text in files (trova)
– Launch an external diff program to compare directories (confronta)
– Search PATH environment for executables (quale)
– Build a call graph, then invoke Graphviz dot to render an image (forte)
→ Script writes results to STDOUT, or generates files/images

##### Important Design Principles and Patterns
- Single-Responsibility: each script encapsulates one distinct CLI utility
- Modular option parsing: use of Getopt::Long or similar for consistent flags
- Separation of concerns:
- CLI interface → argument parsing
- Core logic → file recursion + regex matching
- External integration → system calls to diff or dot
- Platform abstraction: scripts detect OS (Windows vs. Linux) and handle path separators, packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entities
    User["User / CLI Shell"]:::system
    Interpreter["Perl Interpreter"]:::system

    %% Scripts Layer
    subgraph "CLI Utilities"
        Trova["trova.pl"]:::script
        Confronta["confronta.pl"]:::script
        Quale["quale.pl"]:::script
        Forte["forte.pl"]:::script
    end

    %% Build Script
    BuildScript["build.bat (Windows Build)"]:::script

    %% Core Components
    FileSystem["File System"]:::system
    RegexEngine["Perl Regex Engine"]:::core
    PARPacker["PAR::Packer"]:::external

    %% External Tools
    DiffTool["diff Tool"]:::external
    Graphviz["Graphviz dot"]:::external
    OSPath["OS PATH Lookup"]:::external

    %% Outputs
    STDOUT["STDOUT / Generated Outputs"]:::system

    %% Documentation
    README["README.md"]:::system
    License["LICENSE.txt"]:::system

    %% Relationships
    User -->|"invokes"| Interpreter
    User -->|"runs build"| BuildScript

    Interpreter -->|"executes"| Trova
    Interpreter -->|"executes"| Confronta
    Interpreter -->|"executes"| Quale
    Interpreter -->|"executes"| Forte

    BuildScript -->|"packages via"| PARPacker
    BuildScript -->|"produces executables"| Trova
    BuildScript -->|"produces executables"| Confronta
    BuildScript -->|"produces executables"| Quale
    BuildScript -->|"produces executables"| Forte

    %% Trova flow
    Trova -->|"walks directories"| FileSystem
    Trova -->|"applies regex"| RegexEngine
    Trova -->|"writes results to"| STDOUT

    %% Confronta flow
    Confronta -->|"walks directories"| FileSystem
    Confronta -->|"calls external"| DiffTool
    Confronta -->|"writes results to"| STDOUT

    %% Quale flow
    Quale -->|"searches PATH"| OSPath
    Quale -->|"writes results to"| STDOUT

    %% Forte flow
    Forte -->|"walks directories"| FileSystem
    Forte -->|"applies regex"| RegexEngine
    Forte -->|"generates call graph"| STDOUT
    Forte -->|"renders graph via"| Graphviz

    %% Documentation References
    User -->|"views docs"| README
    User -->|"views license"| License

    %% Click Events
    click Trova "https://github.com/guardino/trova/blob/master/./trova.pl"
    click Confronta "https://github.com/guardino/trova/blob/master/./confronta.pl"
    click Quale "https://github.com/guardino/trova/blob/master/./quale.pl"
    click Forte "https://github.com/guardino/trova/blob/master/./forte.pl"
    click BuildScript "https://github.com/guardino/trova/blob/master/./build.bat"
    click README "https://github.com/guardino/trova/blob/master/./README.md"
    click License "https://github.com/guardino/trova/blob/master/./LICENSE.txt"

    %% Styles
    classDef script fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef external fill:#F5B041,stroke:#B9770E,color:#78281F;
    classDef system fill:#D5D8DC,stroke:#7B7D7D,color:#1B2631;
    classDef core fill:#A9DFBF,stroke:#196F3D,color:#145A32;
```
