# bloomberg/memray architecture

> Architecture diagram of the GitHub repository bloomberg/memray, 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/bloomberg/memray
- Repository: https://github.com/bloomberg/memray

## Overview

##### Project Overview
- Type & Purpose: Memray is a memory profiling tool for Python. Its primary function is to track memory allocations – including those in Python code and native C/C++ extensions – and generate various types of reports (flame graphs, tables, live views, etc.) to help analyze and diagnose memory usage and potential leaks.
- Operational Modes: It works as a CLI tool, can be used programmatically via its API, and also supports live terminal interactions and integration with pytest.

##### Major Components & Architecture
a. CLI Interface and Command Routing:
- This component handles user input and dispatches commands such as “run”, “flamegraph”, “table”, “tree”, “live”, “parse”, “summary”, and “stats”.
- Files/Directories Involved: The “src/memray/commands” directory defines the various subcommands (e.g., attach.py, flamegraph.py, run.py) realized in the CLI.

b. Memory Tracking Engine:
- Core Memory Profiling: The engine is responsible for tracking memory usage at the Python level. It sets up hooks to capture call stacks, allocates memory records, and aggregates tracking details.
- Native Integration: Through native extensions implemented in C/C++ (e.g., in “src/memray/_memray” where you see .pyx, .pxd files along with C/C++ source files such as hooks.cpp, snapshot.cpp), Memray enhances Python’s tracking with low-level memory allocation insights.
- API Usage: The tracker is exposed as a context manager (e.g., memray.Tracker) that developers can use inside Python scripts.

c. Report Generation / Reporter Subsystem:
- Reporters Process Data: This component transforms the binary output (result files saved by “memray run”) into reports. Reporters include HTML generators (flamegraph, table), terminal-based views, and TUI-based live dashboards.
- Files/Directories Involved: “src/memray/reporters” contains modules and templates for formatting output (for example, flamegraph.py and table.py alongside the corresponding assets and templates).

d. Build, Configuration, and Testing Infrastructure:
- Build System and Extensions: Configuration files like Dockerfile, Makefile, pyproject.toml, and CMakeLists (inside _memray) indicate how native extensions are built and integrated.
- Testing and Benchmarking: The “tests” directory (with both unit and integration tests) and “benchmarks” directory provide tests and performance measurements, ensuring correct tracking and report generation.
- Documentation: The “docs” directory and associated files offer guidance and detailed usage instructions.

##### Relationships & Data Flow
- User Interaction: The user interacts with Memray via command line or by integrating its API in the application.
- Execution Flow: Running a command (e.g., “memray run my_script.py”) triggers the memory tracker, which monitors Python and native allocations. The tracker logs data into a binary file.
- Report Processing: The corresponding reporter (e.g., “memray flamegraph”) then reads the binary file, applies the transformation (using the reporter templates, styles, and libraries) to generate the flame graph or table view.
- Live Mode Flow: In live mode, a TUI periodically refreshes with aggregated memory statistics – transitioning seamlessly between threads and sorting metrics as needed.

##### Architectural Patterns & Design Principles
- Modular Design: The separation between the CLI layer, memory tracking engine, and reporter subsystem exemplifies “separation of concerns.”
- Extensions & Native Integration: The clear boundary between Python logic and native/C++ code (encapsulated in _memray) shows how performance-critical functionality is isolated.
- Configurability & Extensibility: With support for plugins (e.g., pytest integration via pytest-memray) and user-collected reports, the design promotes extensibility.

##### Technologies & Tools Referenced
- Language/Frameworks: Python (with Cython for native extensions), C/C++, and usage of build tools like Make, Docker, and CMake.
- CI/CD & Testing: GitHub Actions workflows, pre-commit hooks, and various test suites.
- Visualization Libraries & Front-End: HTML, CSS, and JavaScript assets for generating flame graphs and table reports.

## Diagram (Mermaid)

```mermaid
graph TD
    CLI["CLI Interface / API"]
    
    subgraph "Memory Tracking Engine"
        PT["Python Memory Tracking"]
        NT["Native Memory Tracking (_memray)"]
    end
    
    B(("Binary Output"))
    
    subgraph "Reporters"
        FG["Flamegraph Reporter"]
        TR["Table Reporter"]
        LT["Live/TUI Reporter"]
    end
    
    BC["Build & Configuration"]
    TB["Tests & Benchmarks"]
    
    CLI -->|"memray_run"| PT
    CLI -->|"--native_flag"| NT
    PT -->|"allocations"| B
    NT -->|"native_allocations"| B
    B -->|"report_data"| FG
    B -->|"report_data"| TR
    B -->|"report_data"| LT
    BC -->|"build_native_extensions"| NT
    TB -->|"CI_tests"| CLI

    click CLI "https://github.com/bloomberg/memray/tree/main/src/memray/commands"
    click PT "https://github.com/bloomberg/memray/tree/main/src/memray"
    click NT "https://github.com/bloomberg/memray/tree/main/src/memray/_memray"
    click FG "https://github.com/bloomberg/memray/tree/main/src/memray/reporters"
    click TR "https://github.com/bloomberg/memray/tree/main/src/memray/reporters"
    click LT "https://github.com/bloomberg/memray/tree/main/src/memray/reporters"
    click BC "https://github.com/bloomberg/memray/tree/main/Dockerfile"
    click BC "https://github.com/bloomberg/memray/tree/main/Makefile"
    click BC "https://github.com/bloomberg/memray/blob/main/pyproject.toml"
    click BC "https://github.com/bloomberg/memray/blob/main/src/memray/_memray/CMakeLists.txt"
    click TB "https://github.com/bloomberg/memray/tree/main/tests"
    click TB "https://github.com/bloomberg/memray/tree/main/benchmarks"
    
    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef engine fill:#bbf,stroke:#333,stroke-width:2px;
    classDef native fill:#ccf,stroke:#333,stroke-width:2px;
    classDef reporter fill:#cfc,stroke:#333,stroke-width:2px;
    classDef build fill:#fcf,stroke:#333,stroke-width:2px;
    classDef test fill:#ff9,stroke:#333,stroke-width:2px;
    classDef storage fill:#ffc,stroke:#333,stroke-width:2px;
    
    class CLI cli;
    class PT engine;
    class NT native;
    class FG reporter;
    class TR reporter;
    class LT reporter;
    class BC build;
    class TB test;
    class B storage;
```
