# olaf-zero/perf-profiler architecture

> Architecture diagram of the GitHub repository olaf-zero/perf-profiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/olaf-zero/perf-profiler
- Repository: https://github.com/olaf-zero/perf-profiler

## Overview

Perf-profiler is a small Python profiling library. Users wrap code in `Profiler.measure`, which records successful execution durations; they then print summary statistics or generate a plot. The source shows timing, in-memory records, warmup filtering, statistics, plotting, and custom exceptions. There is no persistent store or broader service workflow. Relationships below are limited to calls visible in the sampled core and package exports.

Main entry points: [`src/profiler/core.py`](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py) (Profiler API), [`src/profiler/__init__.py`](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/__init__.py) (Public exports), [`src/profiler/exceptions.py`](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/exceptions.py) (Profiler exceptions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_measurement["Measurement"]
  node_profiler["Profiler API<br/>[core.py]"]
  node_recording["Timed recording<br/>[core.py]"]
  node_records[("In-memory records<br/>[core.py]")]
end

subgraph group_analysis["Analysis and output"]
  node_filtering["Session and warmup filtering<br/>[core.py]"]
  node_statistics["Summary statistics<br/>[core.py]"]
  node_report["Terminal report<br/>[core.py]"]
  node_plot["Plot generation<br/>[core.py]"]
  node_plot_style["Plot styling<br/>[core.py]"]
  node_exceptions["Profiler exceptions<br/>[exceptions.py]"]
end

node_user(("Library user"))
node_package_exports["Public exports<br/>[__init__.py]"]

node_user -->|"uses"| node_profiler
node_profiler -->|"provides"| node_recording
node_recording -->|"appends durations"| node_records
node_profiler -->|"filters sessions"| node_filtering
node_filtering -->|"reads records"| node_records
node_profiler -->|"calculates"| node_statistics
node_profiler -->|"prints"| node_report
node_report -->|"gets valid records"| node_filtering
node_report -->|"gets metrics"| node_statistics
node_profiler -->|"generates"| node_plot
node_plot -->|"selects records"| node_filtering
node_plot -->|"applies style"| node_plot_style
node_profiler -->|"raises"| node_exceptions
node_package_exports -->|"exports"| node_profiler
node_package_exports -->|"exports"| node_exceptions

click node_profiler "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_recording "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_records "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_filtering "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_statistics "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_report "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_plot "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_plot_style "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py"
click node_exceptions "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/exceptions.py"
click node_package_exports "https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_profiler,node_recording,node_records,node_user toneBlue
class node_filtering,node_statistics,node_report,node_plot,node_plot_style,node_exceptions toneAmber
class node_package_exports toneTeal
```

## Components

### Measurement

- [Profiler API](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Timed recording](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [In-memory records](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`

### Analysis and output

- [Session and warmup filtering](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Summary statistics](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Terminal report](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Plot generation](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Plot styling](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/core.py): `src/profiler/core.py`
- [Profiler exceptions](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/exceptions.py): `src/profiler/exceptions.py`

### Other components

- **Library user**
- [Public exports](https://github.com/olaf-zero/perf-profiler/blob/main/src/profiler/__init__.py): `src/profiler/__init__.py`

## Connections

- Library user → Profiler API: uses (evidence: `README.md`)
- Profiler API → Timed recording: provides (evidence: `src/profiler/core.py`)
- Timed recording → In-memory records: appends durations (evidence: `src/profiler/core.py`)
- Profiler API → Session and warmup filtering: filters sessions (evidence: `src/profiler/core.py`)
- Session and warmup filtering → In-memory records: reads records (evidence: `src/profiler/core.py`)
- Profiler API → Summary statistics: calculates (evidence: `src/profiler/core.py`)
- Profiler API → Terminal report: prints (evidence: `src/profiler/core.py`)
- Terminal report → Session and warmup filtering: gets valid records (evidence: `src/profiler/core.py`)
- Terminal report → Summary statistics: gets metrics (evidence: `src/profiler/core.py`)
- Profiler API → Plot generation: generates (evidence: `src/profiler/core.py`)
- Plot generation → Session and warmup filtering: selects records (evidence: `src/profiler/core.py`)
- Plot generation → Plot styling: applies style (evidence: `src/profiler/core.py`)
- Profiler API → Profiler exceptions: raises (evidence: `src/profiler/core.py`)
- Public exports → Profiler API: exports (evidence: `src/profiler/__init__.py`)
- Public exports → Profiler exceptions: exports (evidence: `src/profiler/__init__.py`)