# vmatare/thinkfan architecture

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

- Interactive diagram: https://gitdiagram.com/vmatare/thinkfan
- Repository: https://github.com/vmatare/thinkfan

## Overview

##### Project Type and Purpose
- thinkfan is a lightweight fan control daemon written in C++ for Linux systems. Its main purpose is to monitor temperature sensors (via lm_sensors, NVML for NVIDIA GPUs, and optionally ATA smart) and control hardware fans accordingly.
- The README explains build and installation steps and details configuration options (including YAML support). The project distributes system service scripts for systemd, OpenRC, and sysvinit, which means it is designed to integrate closely with the OS’s service management.

##### File Structure Analysis and Architectural Clues
- Top-level directories such as “src” (core program logic), “include” (headers including NVIDIA-specific NVML integration), “rcscripts” (different initialization frameworks like systemd, OpenRC, sysvinit), and “examples” (sample configuration files) indicate clear separation between core functionality, integration with system services, and configurations.
- The “.github/workflows” directory shows that CI/CD pipelines are used, suggesting a structured development process.
- Presence of CMakeLists.txt and service integration files implies that the building, installation, and deployment aspects are modularized.
- Many source files under “src” (config, driver, sensors, fans, parser, YAML config, etc.) point to a design that separates configuration parsing, hardware monitoring, error handling, and fan control logic into distinct modules.

##### Main Components and Their Interactions
- Configuration Manager: Responsible for reading and parsing configuration (including YAML files). (Files: src/config.cpp, src/yamlconfig.cpp, src/parser.cpp)
- Sensor Manager: Interfaces with hardware sensors. It collects temperature readings using libsensors, LM sensors interface, and NVML for GPU temperatures. (Files: src/sensors.cpp, src/hwmon.cpp, include/nvidia/gdk/nvml.h)
- Fan Controller: Determines and triggers fan speed adjustments based on processed temperature data. (Files: src/fans.cpp, src/driver.cpp)
- Error/Message Handling Module: Manages errors, logging, and user messages. (Files: src/error.cpp, src/message.cpp)
- Service Integration: Scripts provided in “rcscripts” that interact with systemd, OpenRC, or sysvinit to start/stop/restart thinkfan as a system daemon.

##### Architectural Relationships and Patterns
- The Sensor Manager continuously polls or receives data from temperature sensors and passes this data to the Fan Controller.
- The Fan Controller computes desired fan states based on sensor data and commands the hardware via the driver interface.
- Error handling as a side component that listens to events from various modules.
- That integration with system services (via rcscripts) means there’s an external interaction: the system (via systemd/OpenRC/sysvinit) starts, stops, or monitors the thinkfan service.

##### Relevant Technologies and Frameworks
- CMake is used for building; denote a “Build and Installation” component that manages configuration options (debug, release, optional features like NVML, ATA smart, LM sensors, YAML).
- External libraries include libyaml-cpp for YAML support, libsensors for Linux sensor readings, and possibly NVML for GPU monitoring.
- The system-service integration (scripts for systemd, OpenRC, sysvinit) suggests rules and flow between the daemon and operating system environment.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Build and Deployment/CI
    subgraph "Build and Deployment/CI"
        build["CMake Build"]:::buildStyle
        cicd["CI/CD Pipeline"]:::buildStyle
    end

    %% External Libraries
    subgraph "External Libraries"
        lib_yaml["libyaml-cpp"]:::extLib
        lib_sensors["libsensors"]:::extLib
        nvml_lib["NVML"]:::extLib
    end

    %% Core Daemon Modules
    subgraph "Daemon Core"
        config["Configuration Manager"]:::core
        sensor["Sensor Manager"]:::core
        fan["Fan Controller"]:::core
        error["Error/Message Handler"]:::core
    end

    %% Service Integration (System startup scripts)
    subgraph "Service Integration"
        systemd["systemd"]:::service
        openrc["OpenRC"]:::service
        sysvinit["sysvinit"]:::service
    end

    %% Data Flow and Interactions
    build --> config
    cicd --> config

    lib_yaml --> config
    lib_sensors --> sensor
    nvml_lib --> sensor

    config -->|"feeds"| sensor
    config -->|"feeds"| fan
    sensor -->|"reports"| fan

    config ---|"error"| error
    sensor ---|"error"| error
    fan ---|"error"| error

    systemd -->|"manages"| config
    openrc -->|"manages"| config
    sysvinit -->|"manages"| config

    %% Click Events for Component Mappings
    click config "https://github.com/vmatare/thinkfan/blob/master/src/config.cpp"
    click sensor "https://github.com/vmatare/thinkfan/blob/master/src/sensors.cpp"
    click fan "https://github.com/vmatare/thinkfan/blob/master/src/fans.cpp"
    click error "https://github.com/vmatare/thinkfan/blob/master/src/error.cpp"
    click systemd "https://github.com/vmatare/thinkfan/tree/master/rcscripts/systemd"
    click openrc "https://github.com/vmatare/thinkfan/tree/master/rcscripts/openrc"
    click sysvinit "https://github.com/vmatare/thinkfan/tree/master/rcscripts/sysvinit"
    click build "https://github.com/vmatare/thinkfan/blob/master/CMakeLists.txt"
    click cicd "https://github.com/vmatare/thinkfan/tree/master/.github/workflows"
    
    %% Styling for nodes
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef buildStyle fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef service fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef extLib fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
```
