# scottrogowski/code2flow architecture

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

- Interactive diagram: https://gitdiagram.com/scottrogowski/code2flow
- Repository: https://github.com/scottrogowski/code2flow

## Overview

##### Main components
- CLI Interface: The entry point for users (invoked via the command “code2flow” with various options).
- Engine Module: The heart of the processing located primarily in engine.py, which coordinates the parsing and graph generation.
- Language-Specific Parsers: Individual modules for Python (python.py), JavaScript (javascript.py along with get_ast.js and the npm-supported code), PHP (php.py along with get_ast.php), and Ruby (ruby.py). These modules are responsible for translating source files into ASTs for their respective language.
- Core Algorithm Components:
- AST Generation (from provided source files)
- Node and Group Extraction (identifying functions and namespaces)
- Function Call Linkage (connecting call sites to definitions)
- Ambiguity Resolution using heuristics
- Output Generator: The module that ultimately produces the DOT file (or other visual representation) of the call graph.
- External Dependencies: Graphviz is used for visualization, and additional language-specific dependencies (Acorn for JavaScript, PHP-Parser for PHP, Ruby Parser, etc.) are noted.
- Testing Suite: Located in the tests/ directory, which ensures 100% test coverage and validates the functionality across several scenarios and language-specific corner cases.
- Build and Deployment: Supporting files like setup.py, Makefile, and requirements_dev.txt that are used for installation and testing.

##### Relationships and interactions
- The CLI receives user input (files, directories, options such as target function and depth).
- It invokes the Engine, which then:
- Dispatches to the relevant language parser based on file type or explicit options.
- Each parser converts source files into an AST.
- The engine processes the ASTs to extract function definitions (nodes) and group them (namespaces, modules, classes).
- Function calls are analyzed; steps include connecting calling sites with definitions using in-scope variable analysis and heuristics.
- The final graph (DOT file) is produced and sent to Graphviz for visualization.
- Testing modules validate each component of this flow.

##### Important architectural patterns and design principles
- Modular Design: The clear separation of core engine, language-specific parsing logic, and output generation makes the system extensible.
- Separation of Concerns: Different modules handle AST generation, function detection, and graph output separately.
- Heuristic Resolution: Given the dynamic and duck-typed nature of target languages, the design uses heuristics to resolve ambiguities.
- Test-Driven Development: The project maintains a robust testing framework ensuring correctness for each component.

##### Relevant technologies and dependencies
- Python is a primary implementation language.
- JavaScript dependencies are managed via npm (node_modules, package.json).
- PHP and Ruby have their respective parser implementations.
- Graphviz is required for visualization.
- The project uses external libraries/tools like Acorn, PHP-Parser, and Ruby Parser to support AST generation for respective languages.

- Clearly labeled components:
- “CLI/Command Interface” at the top, indicating how the user interacts with the system.
- “Engine” as the core processing module (engine.py).
- “Language Parsers” as sub-components (Python parser, JavaScript parser, PHP parser, Ruby parser).
- “AST Generator” and “Call Graph Builder” as internal stages.
- “DOT File Generator / Graphviz” for output visualization.
- “Testing Suite” with a note on 100% test coverage.
- “Build/Setup Components” like Makefile, setup.py, etc.

##### Detail the essential architectural elements
- Modular nature and the flow of information starting from raw source code, through AST creation and analysis, to the final call graph output.
- Both an overview (high-level component interactions) and the possibility for more detailed expansion within each module (for instance, the AST generation and node linkage process).
- The interactions and dependencies to clearly express the dynamic processing environment Code2flow operates within.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["CLI/Command Interface"]:::cli
    B["Engine Module (engine.py)"]:::engine
    A -->|"input"| B

    subgraph "Language Parsers"
        direction TB
        C["Python Parser (python.py)"]:::lang
        subgraph "JavaScript Parsers"
            direction TB
            D1["JavaScript Parser (javascript.py)"]:::lang
            D1 -->|"helper"| D2["JS AST Helper (get_ast.js)"]:::lang
        end
        subgraph "PHP Parsers"
            direction TB
            E1["PHP Parser (php.py)"]:::lang
            E1 -->|"helper"| E2["PHP AST Helper (get_ast.php)"]:::lang
        end
        F["Ruby Parser (ruby.py)"]:::lang
    end

    %% Dispatch from Engine to Parsers
    B -->|"dispatch"| C
    B -->|"dispatch"| D1
    B -->|"dispatch"| E1
    B -->|"dispatch"| F

    %% Parsers produce ASTs
    C -->|"AST"| G["AST Generator"]:::core
    D2 -->|"AST"| G
    E2 -->|"AST"| G
    F -->|"AST"| G

    %% Core processing steps
    G -->|"extract"| H["Node & Group Extraction"]:::core
    H -->|"linkage"| I["Call Graph Builder & Heuristics"]:::core
    I -->|"generate"| J["DOT File Generator / Graphviz"]:::external

    %% Testing interaction
    J -->|"verified_by"| K["Testing Suite (tests/)"]:::test
    K -->|"feedback"| B

    %% Build & Deployment Components
    subgraph "Build & Deployment"
        direction TB
        L1["Makefile"]:::build
        L2["setup.py"]:::build
        L3["requirements_dev.txt"]:::build
    end
    B -->|"build_depends"| L1
    B -->|"build_depends"| L2
    B -->|"build_depends"| L3

    %% Click Events
    click A "https://github.com/scottrogowski/code2flow/blob/master/setup.py"
    click B "https://github.com/scottrogowski/code2flow/blob/master/code2flow/engine.py"
    click C "https://github.com/scottrogowski/code2flow/blob/master/code2flow/python.py"
    click D1 "https://github.com/scottrogowski/code2flow/blob/master/code2flow/javascript.py"
    click D2 "https://github.com/scottrogowski/code2flow/blob/master/code2flow/get_ast.js"
    click E1 "https://github.com/scottrogowski/code2flow/blob/master/code2flow/php.py"
    click E2 "https://github.com/scottrogowski/code2flow/blob/master/code2flow/get_ast.php"
    click F "https://github.com/scottrogowski/code2flow/blob/master/code2flow/ruby.py"
    click K "https://github.com/scottrogowski/code2flow/tree/master/tests/"
    click L1 "https://github.com/scottrogowski/code2flow/tree/master/Makefile"
    click L2 "https://github.com/scottrogowski/code2flow/blob/master/setup.py"
    click L3 "https://github.com/scottrogowski/code2flow/blob/master/requirements_dev.txt"

    %% Styles
    classDef cli fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef engine fill:#bde0fe,stroke:#000,stroke-width:2px;
    classDef lang fill:#ffc8dd,stroke:#000,stroke-width:2px;
    classDef core fill:#ffec99,stroke:#000,stroke-width:2px;
    classDef external fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef test fill:#d0f4de,stroke:#000,stroke-width:2px;
    classDef build fill:#e0c3fc,stroke:#000,stroke-width:2px;
```
