# davidcarayon/ideatools architecture

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

- Interactive diagram: https://gitdiagram.com/davidcarayon/ideatools
- Repository: https://github.com/davidcarayon/ideatools

## Overview

##### Main Components
- Entry Points:
- Command-Line Interface (invoking functions directly, e.g. diag_idea()).
- Graphical User Interface provided by runGUI() and the Shiny app (inst/ShinyApp/app.R).
- Core Modules:
- Data Input: read_idea() for file validation and data extraction, and old_idea() for legacy calculator handling.
- Computation Engine: compute_idea() which calculates the IDEA components based on the input.
- Visualization: plot_idea() for generating graphical outputs.
- Reporting: write_idea() which handles the export of raw graphs and formatted reports.
- Orchestrator: diag_idea() that coordinates the entire workflow by sequentially calling the appropriate modules.
- Auxiliary Modules:
- Additional utilities in utils.R and theme functions in themes.R.
- The jsonify module (mentioned in the README as jsonify2()) which converts Excel data to JSON for use by external systems like WEBIDEA.
- Documentation & Support Files:
- The man, docs, and vignettes directories, which document the functionality and usage.
- Test and Continuous Integration configurations (.github workflows, .gitlab-ci.yml, etc.)
- External Dependencies:
- A dependency on LaTeX (for PDF reports) and Helvetica font.
- R interpreter and additional R packages (for processing, Shiny for the GUI).

##### Relationships and Interactions
- The diag_idea() function acts as the central "orchestrator" calling:
- The Reading module (read_idea() / old_idea()) to validate and extract input data.
- The Computation module (compute_idea()) to compute indicators.
- The Plotting module (plot_idea()) to produce figures.
- The Reporting module (write_idea()) to finally export results in diverse formats.
- The runGUI() function provides a UI-based access point that eventually triggers the same backend workflow but through a Shiny application.
- There are dependencies among the R functions—the output of read_idea() is input for compute_idea(), whose output feeds plot_idea() and write_idea().

##### Architectural Patterns and Design Principles
- Modular Design: Each function (module) handles a specific part of the diagnostic pipeline so that responsibilities are clearly separated.
- Layered Approach: The system can be visualized as layers:
- Interface Layer (CLI and GUI),
- Processing Layer (data reading, computation, plotting),
- Output Layer (report generation).
- Extensibility: The use of helpers, themes, and utility functions (utils.R, themes.R) implies that the system is designed for adaptability (e.g., supporting new input formats or output types).

##### Specific Technologies, Frameworks, and Libraries
- R as the core language/platform and the R package structure (modules in R/ directory, DESCRIPTION, NAMESPACE).
- Shiny framework for the GUI (located in inst/ShinyApp).
- LaTeX for PDF report generation.
- pkgdown for generating online documentation.
- Version control and CI/CD systems, as seen from .github workflows and .gitlab-ci.yml.

##### Elements
- Clear Labels: For each component (input, compute, plot, reporting, orchestration, GUI).

##### Putting It All Together
- How the diag_idea() function “glues” all the modules together.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Interface Layer
    subgraph "Interface Layer"
        CLI["Orchestrator (diag_idea)"]:::interface
        GUI["GUI Entry (runGUI)"]:::interface
        Shiny["Shiny Application (app.R)"]:::interface
    end

    %% Processing Layer
    subgraph "Processing Layer"
        subgraph "Data Input Module"
            Read["read_idea()"]:::core
            Legacy["old_idea()"]:::core
        end
        Compute["Computation Engine (compute_idea)"]:::core
        Visual["Visualization (plot_idea)"]:::core
        Report["Reporting (write_idea)"]:::core
    end

    %% Auxiliary & Utilities
    subgraph "Auxiliary & Utilities"
        Utils["Utilities (utils.R)"]:::aux
        Themes["Theme Functions (themes.R)"]:::aux
        Jsonify["Jsonify Module (jsonify2)"]:::aux
    end

    %% Documentation & CI/CD
    subgraph "Documentation & CI/CD"
        Docs["Documentation & Support (man/, docs/, vignettes/)"]:::doc
        CI["CI/CD Configurations (.github/workflows, .gitlab-ci.yml)"]:::doc
    end

    %% Connections between Interface and Processing Layers
    GUI -->|"triggers"| CLI
    Shiny -->|"triggers"| CLI
    CLI -->|"calls"| Read
    CLI -->|"calls"| Legacy
    Read -->|"provides data"| Compute
    Legacy -->|"provides data"| Compute
    CLI -->|"orchestrates"| Compute
    Compute -->|"outputs for plot"| Visual
    Compute -->|"outputs for report"| Report

    %% Auxiliary dependencies
    Read ---|"utilizes"| Utils
    Legacy ---|"utilizes"| Utils
    Compute ---|"utilizes"| Utils
    Compute ---|"utilizes"| Themes
    Visual ---|"utilizes"| Themes
    Report ---|"utilizes"| Themes
    Read ---|"optionally converts"| Jsonify

    %% Documentation linkage (contextual)
    Docs --- CI

    %% Click Events
    click CLI "https://github.com/davidcarayon/ideatools/blob/master/R/diag_idea.R"
    click GUI "https://github.com/davidcarayon/ideatools/blob/master/R/runGUI.R"
    click Shiny "https://github.com/davidcarayon/ideatools/blob/master/inst/ShinyApp/app.R"
    click Read "https://github.com/davidcarayon/ideatools/blob/master/R/read_idea.R"
    click Legacy "https://github.com/davidcarayon/ideatools/blob/master/R/old_idea.R"
    click Compute "https://github.com/davidcarayon/ideatools/blob/master/R/compute_idea.R"
    click Visual "https://github.com/davidcarayon/ideatools/blob/master/R/plot_idea.R"
    click Report "https://github.com/davidcarayon/ideatools/blob/master/R/write_idea.R"
    click Utils "https://github.com/davidcarayon/ideatools/blob/master/R/utils.R"
    click Themes "https://github.com/davidcarayon/ideatools/blob/master/R/themes.R"
    click Jsonify "https://github.com/davidcarayon/ideatools/blob/master/man/jsonify2.Rd"
    click Docs "https://github.com/davidcarayon/ideatools/tree/master/docs/"
    click CI "https://github.com/davidcarayon/ideatools/tree/master/.github/workflows"

    %% Styles
    classDef interface fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef aux fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef doc fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
```
