# jrfonseca/gprof2dot architecture

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

- Interactive diagram: https://gitdiagram.com/jrfonseca/gprof2dot
- Repository: https://github.com/jrfonseca/gprof2dot

## Overview

##### Project Type and Purpose
- The README clearly explains the supported profiler formats, usage instructions, and a sample output image, while the file tree reveals the main script file (gprof2dot.py), setup files (setup.py, setup.cfg, pyproject.toml), extensive tests for different input formats, and GitHub workflows for CI.

##### Analyzing the File Structure
- At the root, the key executable script is gprof2dot.py.
- There are configuration and packaging files (pyproject.toml, setup.py, setup.cfg) that suggest a standard Python package structure.
- The tests directory contains test cases for various input formats (axe, callgrind, collapse, dtrace, hprof, json, oprofile, perf, prof, pstats, sleepy, sysprof, and xperf), each with subdirectories. This indicates a strong commitment to validating parser functionality for multiple profiling outputs.
- The .github directory holds CI/CD workflows (build and test jobs) which automate builds and tests.
- Supporting files such as LICENSE.txt and README.md complete the project.

##### Key Components
a. Command-Line Interface (CLI) and Entry Point:
- The gprof2dot.py script acts as the entry point and parses command-line arguments (such as options for thresholds, format, output file, etc.). It interfaces with the user and processes their input.

b. Input Parsers for Various Profiling Formats:
- These components accept raw profiler output and produce a standardized internal representation of the call graph.

c. Core Conversion and Graph Generation Engine:
- This part takes the parsed profiling data, applies heuristics (like threshold filtering, node/edge pruning, and recursive function time propagation), and transforms it into the dot graph representation.
- It embodies the core logic responsible for mapping function call relationships to nodes and the call frequency/duration to edge weights.

d. Output Generation:
- The resulting dot graph (as plain text following Graphviz’s language) becomes the output file or stream that the user can pipe to Graphviz’s “dot” command.
- This component is responsible for formatting the node labels (including self-time, total time, call counts, etc.) and edge labels.

e. Packaging and Deployment Configuration:
- Files like setup.py, setup.cfg, pyproject.toml represent the packaging and dependency management system. They ensure that the tool can be installed and executed on any platform with Python and Graphviz installed.
- It might be helpful to note these as auxiliary components that support deployment.

f. Continuous Integration / Testing Framework:
- The .github/workflows directory contains CI workflows (e.g., build.yml, testOnly.yml) that run automated tests.
- The tests directory itself is structured to cover a plethora of profiling formats, highlighting a robust testing strategy.
- As “Test Suites” connected to the main components to show continuous feedback on quality and integration.

##### Relationships and Interactions
- User Input (via CLI arguments) feeds directly into the gprof2dot.py entry point.
- This entry point routes the input to specific Input Parser components based on the selected format (e.g., using a flag such as -f axe or -f callgrind).
- Each Parser module processes raw profile data into an internal call graph representation.
- The formatted graph is then output as a dot file, which the user can redirect to Graphviz for rendering.
- Testing frameworks interact with these components by providing sample profile inputs (found under the tests directory) and verifying that the output matches expected results.
- CI/CD workflows automate running these tests on every commit to ensure system stability.

##### Highlighting Architectural Patterns and Design Principles
- Modularity: The design benefits from clear separation between input parsing, internal representation transformation, and output generation.
- Extensibility: The system is designed to support many profiling formats. This can be reflected by grouping parser components under a common interface.
- Single Responsibility: Each component (CLI processing, parsing, conversion, output formatting) does one specific job.
- Test-Driven Approach: The extensive tests indicate an architecture that supports validation of each module in isolation.

## Diagram (Mermaid)

```mermaid
graph TD
    A["User Input"]:::ext
    B["CLI / Entry Point (gprof2dot.py)"]:::cli
    A -->|"CLI_arguments"| B

    %% Input Parsers (individual parser modules)
    C1["Axe Parser"]:::parser
    C2["Callgrind Parser"]:::parser
    C3["Dtrace Parser"]:::parser
    C4["Hprof Parser"]:::parser
    C5["JSON Parser"]:::parser
    C6["OProfile Parser"]:::parser
    C7["Perf Parser"]:::parser
    C8["Prof Parser"]:::parser
    C9["PStats Parser"]:::parser
    C10["Sleepy Parser"]:::parser
    C11["Sysprof Parser"]:::parser
    C12["Xperf Parser"]:::parser

    %% Connections from CLI to each Input Parser
    B -->|"invoke"| C1
    B -->|"invoke"| C2
    B -->|"invoke"| C3
    B -->|"invoke"| C4
    B -->|"invoke"| C5
    B -->|"invoke"| C6
    B -->|"invoke"| C7
    B -->|"invoke"| C8
    B -->|"invoke"| C9
    B -->|"invoke"| C10
    B -->|"invoke"| C11
    B -->|"invoke"| C12

    %% All parser outputs feed into the Conversion Engine
    C1 -->|"parsed_data"| D
    C2 -->|"parsed_data"| D
    C3 -->|"parsed_data"| D
    C4 -->|"parsed_data"| D
    C5 -->|"parsed_data"| D
    C6 -->|"parsed_data"| D
    C7 -->|"parsed_data"| D
    C8 -->|"parsed_data"| D
    C9 -->|"parsed_data"| D
    C10 -->|"parsed_data"| D
    C11 -->|"parsed_data"| D
    C12 -->|"parsed_data"| D

    %% Core Conversion & Graph Generation Engine
    D["Core Conversion Engine (gprof2dot.py)"]:::core
    D -->|"conversion"| E

    %% Output Generation Component
    E["Output Generation (DOT Formatting - gprof2dot.py)"]:::output
    E -->|"dot_output"| F["Graphviz (dot)"]:::ext

    %% Packaging & Deployment Configuration
    subgraph "Packaging & Deployment"
        G1["setup.py"]:::config
        G2["setup.cfg"]:::config
        G3["pyproject.toml"]:::config
    end
    B -.->|"configured_by"| G1
    B -.->|"configured_by"| G2
    B -.->|"configured_by"| G3

    %% Continuous Integration & Testing Framework
    subgraph "Continuous Integration & Testing"
        H[".github/workflows"]:::ci
        I["Test Suites (tests/)"]:::ci
    end
    B -.->|"tested_by"| H
    B -.->|"tested_by"| I

    %% Click Events
    click B "https://github.com/jrfonseca/gprof2dot/blob/main/gprof2dot.py"
    click C1 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/axe"
    click C2 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/callgrind"
    click C3 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/dtrace"
    click C4 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/hprof"
    click C5 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/json"
    click C6 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/oprofile"
    click C7 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/perf"
    click C8 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/prof"
    click C9 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/pstats"
    click C10 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/sleepy"
    click C11 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/sysprof"
    click C12 "https://github.com/jrfonseca/gprof2dot/tree/main/tests/xperf"
    click G1 "https://github.com/jrfonseca/gprof2dot/blob/main/setup.py"
    click G2 "https://github.com/jrfonseca/gprof2dot/blob/main/setup.cfg"
    click G3 "https://github.com/jrfonseca/gprof2dot/blob/main/pyproject.toml"
    click H "https://github.com/jrfonseca/gprof2dot/tree/main/.github/workflows"
    click I "https://github.com/jrfonseca/gprof2dot/tree/main/tests"

    %% Styles
    classDef cli fill:#B3D4FC,stroke:#1F77B4,stroke-width:2px;
    classDef parser fill:#FEEBC8,stroke:#D2691E,stroke-width:2px;
    classDef core fill:#F8CDD3,stroke:#E24A4A,stroke-width:2px;
    classDef output fill:#C5EDC7,stroke:#3CB371,stroke-width:2px;
    classDef config fill:#E8E8E8,stroke:#808080,stroke-width:2px;
    classDef ci fill:#FFF3B0,stroke:#FFBF00,stroke-width:2px;
    classDef ext fill:#F0E68C,stroke:#DAA520,stroke-width:2px;
```
