# flowr-analysis/flowr architecture

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

- Interactive diagram: https://gitdiagram.com/flowr-analysis/flowr
- Repository: https://github.com/flowr-analysis/flowr

## Overview

Below are detailed guidelines tailored to flowR’s architecture:

##### Main Components
- Command Line & REPL Interface: This is the entry point for users. It is represented by components in the “src/cli” directory (including both the REPL and various CLI apps such as “benchmark-app”, “slicer-app”, or “statistics-app”). This layer handles user commands, input file selection, and dispatching operations.
- Abstract Interpretation and Parsing Modules: These are responsible for interpreting the input R code. Key pieces are found in “src/abstract-interpretation”, “src/core/steps”, and in the parser sections of “src/r-bridge/lang-4.x/ast”. They process the source code into an intermediate representation (AST, normalized AST), and then apply both static analysis and dataflow extraction.
- Dataflow Analysis Engine: Distributed throughout “src/dataflow”, this module builds and maintains dataflow graphs, handles environments, links and graph resolution. It is critical for both the slicing and query operations.
- Query & Slicing Engine: Under “src/queries” and “src/slicing”, these components implement the domain-specific queries (e.g., dependencies, lineage, static slicing queries) and perform the slicing operation to extract the relevant portions of the code.
- R Bridge & Integration: Found extensively in “src/r-bridge”, this component provides support for language-specific constructs, interfacing with R’s parsing mechanisms (even including WebAssembly modules for tree-sitter support) to connect R’s semantics to flowR’s analysis.
- Benchmarking & Statistics: These modules (in “src/benchmark” and “src/statistics”) handle performance measurements and statistical analyses of processed data, which may feed back into both quality assurance and optimization efforts.
- Utilities & Documentation: The “src/util” provides helper functions (for logging, file operations, ANSI formatting, etc.) while “src/documentation” and the “wiki” folder serve external documentation and usage examples, but can be abstracted as supporting components in the overall architecture.

##### Relationships and Interactions
- The CLI layer collects user input (possibly via Docker, npm, or direct command-line calls) and passes the R source files onto the Core Pipeline Executor.
- The Pipeline Executor coordinates various processing stages: it sends source code to the Parser/Abstract Interpretation modules, which build an internal representation (AST and normalized AST).
- Next, the Dataflow Analysis Engine processes the intermediate representations to generate data/control flow graphs and compute dependencies.
- The Query Engine (including slicing queries) operates on these representations, providing targeted outputs such as slices or dependency graphs.
- The R Bridge acts as an intermediary layer that deals specifically with nuances of the R language—processing its syntax and semantics using dedicated parsers and tree-sitter executables.
- Supporting modules for performance benchmarking and statistical analysis are integrated within the pipeline to provide feedback on efficiency and to quantify aspects of the analysis.

##### Architectural Patterns & Design Principles
- Modular Architecture: The project follows a clear separation of concerns, with distinct modules for CLI, core processing, language parsing, dataflow analysis, queries, and utilities.
- Pipeline/Step-Execution Pattern: The “pipeline” design, seen in “src/core/steps” and “src/core/pipeline”, supports sequential stages in program analysis.
- Abstraction & Extensibility: The design encourages modularity (e.g., separate “built-in” handling under dataflow processes, abstract interpretation modules, and query catalogs) to allow for easy extended analyses.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-Level Components
    cli["CLI/REPL (src/cli)"]:::ui
    core["Core Pipeline Executor (src/core)"]:::processing
    parser["Abstract Interpretation & Parsing Modules (src/abstract-interpretation, src/core/steps, src/r-bridge/lang-4.x/ast)"]:::processing
    rbridge["R Bridge & Integration (src/r-bridge)"]:::processing
    dataflow["Dataflow Analysis Engine (src/dataflow)"]:::analysis
    query["Query & Slicing Engine (src/queries, src/slicing)"]:::analysis
    benchmark["Benchmarking & Statistics (src/benchmark, src/statistics)"]:::support
    util["Utilities & Documentation (src/util, src/documentation)"]:::support

    %% Data Flow
    cli -->|"collects_input"| core
    core -->|"executes_pipeline"| parser
    parser -->|"generates_IR"| dataflow
    parser -->|"handles_RSyntax"| rbridge
    rbridge -->|"translates_R"| dataflow
    dataflow -->|"provides_analysis"| query
    benchmark -->|"performance_feedback"| core

    %% Supporting module connection (optional)
    core -->|"uses_helpers"| util

    %% Click Events
    click cli "https://github.com/flowr-analysis/flowr/tree/main/src/cli"
    click core "https://github.com/flowr-analysis/flowr/tree/main/src/core"
    click core "https://github.com/flowr-analysis/flowr/blob/main/src/core/pipeline-executor.ts"
    click core "https://github.com/flowr-analysis/flowr/tree/main/src/core/steps"
    click parser "https://github.com/flowr-analysis/flowr/tree/main/src/abstract-interpretation"
    click parser "https://github.com/flowr-analysis/flowr/tree/main/src/r-bridge/lang-4.x/ast"
    click dataflow "https://github.com/flowr-analysis/flowr/tree/main/src/dataflow"
    click query "https://github.com/flowr-analysis/flowr/tree/main/src/queries"
    click query "https://github.com/flowr-analysis/flowr/tree/main/src/slicing"
    click rbridge "https://github.com/flowr-analysis/flowr/tree/main/src/r-bridge"
    click benchmark "https://github.com/flowr-analysis/flowr/tree/main/src/benchmark"
    click benchmark "https://github.com/flowr-analysis/flowr/tree/main/src/statistics"
    click util "https://github.com/flowr-analysis/flowr/tree/main/src/util"
    click util "https://github.com/flowr-analysis/flowr/tree/main/src/documentation"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef processing fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef analysis fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
