# pawelkn/rainflow architecture

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

- Interactive diagram: https://gitdiagram.com/pawelkn/rainflow
- Repository: https://github.com/pawelkn/rainflow

## Overview

##### Project type and purpose (from README + tree)
This repo is a **small C++ algorithm library** (not a service/app) implementing the **ASTM E1049-85 rainflow cycle counting algorithm** for fatigue analysis.

Key characteristics:
- **Public API:** `RainFlow::count_cycles(series, binSize?)` and `RainFlow::extract_cycles(series)`
- **Runtime dependencies:** **none** (zero deps)
- **Build/test tooling:** **CMake** (`CMakeLists.txt`), optional **GoogleTest** only for tests, **Dockerfile** for reproducible builds, **GitHub Actions** workflow for CI

- **A reusable library module** + **consumers** (example app, downstream apps)
- **Build + CI pipeline** (CMake, Docker, GitHub Actions)
- **Test harness** (GTest)

##### File structure to architectural elements

- `src/rainflow.h`
**Public interface / API contract** (types: `Series`, `Counts`, `Cycles`, `Cycle`; functions)
- `src/rainflow.cpp`
**Core algorithm implementation** (internal steps of rainflow counting)
- `example/example_rainflow.cpp`, `example/samples.txt`
**Consumer executable** demonstrating library usage + sample input file
- `test/test_rainflow.cpp`
**Unit tests** (requires GoogleTest locally)
- `CMakeLists.txt`
**Build orchestration** (targets likely: library, example, tests)
- `Dockerfile`
**Build + run environment** (compiles and runs example/tests)
- `.github/workflows/test.yml`
**CI pipeline** (build + test)
- `.dockerignore`, `.gitignore`, `LICENSE.txt`, `README.md`
Supporting repo artifacts

##### API Layer
- `count_cycles(series, binSize)`
- `extract_cycles(series)`
- Types: `Series`, `Cycle`, `Cycles`, `Counts`
##### Preprocessing / Reversal (Turning Point) Detection
- Takes raw samples → filtered sequence of extrema (common step in rainflow)
##### Cycle Extraction Core
- Stack-based traversal / pairing logic producing half/full cycles
- Outputs `Cycles` (range, mean, count, start/end indices)
##### Binning / Aggregation
- Converts cycles → `Counts` map keyed by range bins (uses `binSize`)

- `Series` → Turning Points → Extraction Core → `Cycles`
- `Cycles` → Binning/Aggregation → `Counts`

Goal: capture the repo’s operational workflow (this is the “system” part that matters most here).

**Include nodes:**
- Developer machine
- CMake build system
- Targets:
- `example_rainflow` executable
- `test_rainflow` executable
- (library target if defined in `CMakeLists.txt`)
- GoogleTest (only as test dependency)
- Docker image build (Dockerfile)
- GitHub Actions workflow (`.github/workflows/test.yml`)

- Developer → CMake configure/build → produces binaries
- `test_rainflow` → links against GoogleTest (local requirement)
- Docker build → runs CMake build inside container → runs example/tests
- GitHub Actions → runs workflow → builds/tests (optionally via Docker or directly via CMake, depending on `test.yml`)

##### Relationships and interactions to highlight
Because this is a library, interactions are mostly **function calls and compilation/linking**, not runtime messaging.

Call relationships (runtime):
- Example/External code calls:
- `RainFlow::count_cycles(series, binSize)` → returns `Counts`
- `RainFlow::extract_cycles(series)` → returns `Cycles`

Build relationships (compile/link time):
- `example/example_rainflow.cpp` **includes** `rainflow.h` and links against compiled object(s) from `rainflow.cpp`
- `test/test_rainflow.cpp` includes `rainflow.h` + links:
- rainflow objects
- GoogleTest (only for tests)

Tooling relationships:
- Docker encapsulates CMake + compiler toolchain + execution
- GitHub Actions triggers build/test on push/PR

##### Practical “don’t overthink it” checklist (maximize component separation)
To be “very detailed” without inventing systems, separate into these components explicitly:
- Public API (header)
- Algorithm core (cpp)
- Preprocessing step
- Cycle extraction step
- Binning/aggregation step
- Example CLI
- Sample input file
- Unit test binary
- GoogleTest dependency (test-only)
- CMake build
- Docker build/run
- GitHub Actions workflow

That set is the best “as many components as possible” decomposition that still remains truthful to the repository.

- Example CLI / External App → Rainflow API → (Turning Points → Extraction → Binning) → Counts/Cycles
- Example CLI → samples.txt

- GitHub Actions → (Docker optional) → CMake → build targets → run tests
- Developer → CMake → build/run example & tests
- Test target → GoogleTest

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Runtime / In-process usage
%% =========================
subgraph "Runtime (In-process)"
direction TB

subgraph "Consumers"
direction TB
EXT["External Application / User Code"]:::consumer
EXE["Example CLI (example_rainflow)"]:::exe
SAMPLES["samples.txt (input series)"]:::doc
end

subgraph "Rainflow Library (C++ module)"
direction TB

subgraph "Public API"
direction TB
HPP["rainflow.h (Public API Contract)\nRainFlow::{count_cycles(), extract_cycles()}\nTypes: Series, Cycle, Cycles, Counts"]:::api
end

subgraph "Implementation"
direction TB
CPP["rainflow.cpp (Core Implementation)"]:::impl
TP["Preprocessing: Turning Point Detection\n(raw samples → extrema)"]:::lib
CORE["Cycle Extraction Core\n(stack-based pairing → half/full cycles)"]:::lib
BIN["Binning / Aggregation\n(Cycles → Counts bins via binSize)"]:::lib
end

CYCLES["Cycles (output)"]:::datatype
COUNTS["Counts (output)"]:::datatype
end

%% Runtime call/data flows
EXT -->|"calls RainFlow::extract_cycles(Series)"| HPP
EXT -->|"calls RainFlow::count_cycles(Series,binSize)"| HPP

EXE -->|"calls"| HPP
EXE -->|"reads"| SAMPLES
SAMPLES -->|"Series"| HPP

HPP -->|"delegates"| CPP
CPP -->|"Series"| TP
TP -->|"Turning points"| CORE
CORE -->|"Cycles"| CYCLES
CYCLES -->|"Cycles"| BIN
BIN -->|"Counts"| COUNTS

HPP -->|"returns"| CYCLES
HPP -->|"returns"| COUNTS

end

%% =========================
%% Build / Test / Delivery
%% =========================
subgraph "Build, Test & Delivery"
direction TB

subgraph "Local Development"
direction TB
DEV["Developer Machine"]:::external
CMAKE["CMake Build System"]:::tool
T_LIB["Library Target\n(compile src/rainflow.cpp + headers)"]:::artifact
T_EX["example_rainflow Target\n(executable)"]:::artifact
T_TEST["test_rainflow Target\n(test executable)"]:::artifact
end

subgraph "Test Dependency"
direction TB
GTEST["GoogleTest (test-only dependency)"]:::externaldep
end

subgraph "Reproducible Environment"
direction TB
DOCKER["Docker Build/Run Environment"]:::tool
IMG["Container Image\n(toolchain + build outputs)"]:::artifact
end

subgraph "CI"
direction TB
GHA["GitHub Actions Workflow\n(build + test)"]:::tool
end

%% Build relationships (dashed)
DEV -.->|"configure/build"| CMAKE
CMAKE -.->|"builds"| T_LIB
CMAKE -.->|"builds"| T_EX
CMAKE -.->|"builds"| T_TEST

T_EX -.->|"links against"| T_LIB
T_TEST -.->|"links against"| T_LIB
T_TEST -.->|"links against"| GTEST

DOCKER -.->|"runs CMake build"| CMAKE
DOCKER -.->|"produces"| IMG

GHA -.->|"triggers"| DOCKER
GHA -.->|"or runs"| CMAKE
GHA -.->|"executes"| T_TEST

end

%% =========================
%% Click Events (from mapping)
%% =========================
click HPP "https://github.com/pawelkn/rainflow/blob/master/src/rainflow.h"
click CPP "https://github.com/pawelkn/rainflow/blob/master/src/rainflow.cpp"
click EXE "https://github.com/pawelkn/rainflow/blob/master/example/example_rainflow.cpp"
click SAMPLES "https://github.com/pawelkn/rainflow/blob/master/example/samples.txt"
click T_TEST "https://github.com/pawelkn/rainflow/blob/master/test/test_rainflow.cpp"
click CMAKE "https://github.com/pawelkn/rainflow/blob/master/CMakeLists.txt"
click DOCKER "https://github.com/pawelkn/rainflow/tree/master/Dockerfile"
click GHA "https://github.com/pawelkn/rainflow/blob/master/.github/workflows/test.yml"

%% Supporting repo artifacts (clickable but not cluttering runtime graph)
SUPPORT_README["README.md"]:::doc
SUPPORT_LICENSE["LICENSE.txt"]:::doc
SUPPORT_DIGNORE[".dockerignore"]:::doc
SUPPORT_GIGNORE[".gitignore"]:::doc

click SUPPORT_README "https://github.com/pawelkn/rainflow/blob/master/README.md"
click SUPPORT_LICENSE "https://github.com/pawelkn/rainflow/blob/master/LICENSE.txt"
click SUPPORT_DIGNORE "https://github.com/pawelkn/rainflow/blob/master/.dockerignore"
click SUPPORT_GIGNORE "https://github.com/pawelkn/rainflow/blob/master/.gitignore"

%% =========================
%% Styling
%% =========================
classDef consumer fill:#2ecc71,stroke:#1e8449,color:#0b2e13,stroke-width:1px
classDef exe fill:#27ae60,stroke:#1e8449,color:#ffffff,stroke-width:1px
classDef doc fill:#ecf0f1,stroke:#7f8c8d,color:#2c3e50,stroke-width:1px
classDef api fill:#3498db,stroke:#21618c,color:#ffffff,stroke-width:1px
classDef impl fill:#2e86c1,stroke:#1b4f72,color:#ffffff,stroke-width:1px
classDef lib fill:#5dade2,stroke:#1b4f72,color:#0b2239,stroke-width:1px
classDef datatype fill:#d6eaf8,stroke:#21618c,color:#1b4f72,stroke-width:1px
classDef tool fill:#f39c12,stroke:#b9770e,color:#ffffff,stroke-width:1px
classDef artifact fill:#fdebd0,stroke:#b9770e,color:#6e2c00,stroke-width:1px
classDef external fill:#bdc3c7,stroke:#7f8c8d,color:#2c3e50,stroke-width:1px
classDef externaldep fill:#d5d8dc,stroke:#7f8c8d,color:#2c3e50,stroke-width:1px
```
