# florianbellmann/fancontrol architecture

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

- Interactive diagram: https://gitdiagram.com/florianbellmann/fancontrol
- Repository: https://github.com/florianbellmann/fancontrol

## Overview

##### Project Type and Purpose
- This is a small, specialized service (which can run as a Docker container or directly on the Raspberry Pi) that monitors the CPU temperature and adjusts the fan speed accordingly.
- The README emphasizes that it is used to control the fan speed and CPU temperature on Raspberry Pi devices, while the file tree indicates support for both Python and Node.js implementations.
- The project is lightweight, meant to run either as a systemd service (using the provided fancontrol.service and install scripts) or within a containerized environment (Dockerfile and Dockerfile_py).

##### Analyzing the File Structure
- Top-Level Files:
- Dockerfile and Dockerfile_py: Indicate options for containerization (possibly one for a Node-based approach and another for a Python-based approach).
- README.md and LICENSE: Standard project information.
- .gitignore: Source control preferences.
- index.js, package.json, package-lock.json: Define a Node.js component that may serve as a controller or API layer.
- calib_fan.py and fan_ctrl.py: Python scripts responsible for calibrating and controlling the fan, which likely interact directly with hardware.
- fancontrol.service: A systemd service file that sets up the service on a Raspberry Pi.
- install_service.sh and run.sh: Scripts to install or execute the service.

##### Insights from the README
- The README clarifies that this project is a service (or Docker container) for controlling fan speed and monitoring CPU temperature on a Raspberry Pi.
- The note about potentially requiring absolute paths suggests that some configuration may be necessary depending on the deployment environment.

##### Main Components of the System
- Hardware/Platform:
- Raspberry Pi hardware, including temperature sensors and a fan (direct hardware interface).
- Fan Control Service:
- Python-based modules (calib_fan.py and fan_ctrl.py): These are the heart of the logic for calibrating and adjusting the fan speed.
- Node.js module (index.js): Likely provides a control loop, API endpoints, or integration logic to orchestrate or monitor the Python scripts.
- Containerization & Deployment:
- Dockerfiles allow the project to be deployed in a containerized environment.
- systemd Service (fancontrol.service) and installation scripts (install_service.sh, run.sh) support a traditional service installation on a Raspberry Pi.
- Configuration and Dependency Management:
- package.json/package-lock.json indicate Node.js dependencies.
- Additional custom configuration may be noted in the scripts.

##### Relationships and Interactions between Components
- The system first gathers the current CPU temperature from the Raspberry Pi’s sensors.
- This data is handled by the Python modules: One script (calib_fan.py) could be used for calibrating fan control parameters, and the other (fan_ctrl.py) for adjusting fan speed based on real-time temperature readings.
- The Node.js component (index.js) might act as the orchestrator, API gateway, or logging interface that triggers or interacts with the Python modules.
- The whole application is wrapped and deployed via Docker (using Dockerfile or Dockerfile_py) or installed as a systemd service (via fancontrol.service and install_service.sh).

##### Architectural Patterns and Key Technologies
- Service/Daemon Architecture: The system is designed to run continuously, either as a containerized service or systemd daemon.
- Modular Design: Separation between the Python logic for hardware control and the Node.js portion for orchestration or external interfacing.
- Containerization: The Dockerfiles indicate a container aspect, making deployment consistent across environments.
- Scripting and Automation: Shell scripts provide convenient installation and launch mechanisms.
- Design Principle: Clear separation of concerns (calibration vs. direct control vs. service orchestration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Environment"
        HW1["CPU Temperature Sensor"]:::hardware
        HW2["Fan Hardware"]:::hardware
    end

    subgraph "Python Fan Control"
        P1["calib_fan.py"]:::python
        P2["fan_ctrl.py"]:::python
    end

    subgraph "Node.js Orchestrator"
        N1["index.js"]:::node
    end

    subgraph "Deployment Options"
        subgraph "Docker Container"
            D2["Dockerfile"]:::container
            D3["Dockerfile_py"]:::container
        end
        subgraph "Systemd Service"
            S2["fancontrol.service"]:::service
            S3["install_service.sh"]:::service
            S4["run.sh"]:::script
        end
    end

    HW1 -->|"sends_temp"| P1
    P1 -->|"calibrates"| P2
    P2 -->|"controls"| HW2
    N1 -->|"orchestrates"| P1
    N1 -->|"orchestrates"| P2
    D2 -->|"deploys"| N1
    S2 -->|"deploys"| N1
    S3 -->|"installs"| S4
    S4 -->|"starts"| N1

    click P1 "https://github.com/florianbellmann/fancontrol/blob/master/calib_fan.py"
    click P2 "https://github.com/florianbellmann/fancontrol/blob/master/fan_ctrl.py"
    click N1 "https://github.com/florianbellmann/fancontrol/blob/master/index.js"
    click D2 "https://github.com/florianbellmann/fancontrol/tree/master/Dockerfile"
    click D3 "https://github.com/florianbellmann/fancontrol/tree/master/Dockerfile_py"
    click S2 "https://github.com/florianbellmann/fancontrol/blob/master/fancontrol.service"
    click S3 "https://github.com/florianbellmann/fancontrol/blob/master/install_service.sh"
    click S4 "https://github.com/florianbellmann/fancontrol/blob/master/run.sh"

    class HW1,HW2 hardware
    class P1,P2 python
    class N1 node
    class D2,D3 container
    class S2,S3 service
    class S4 script

    classDef hardware fill:#F08080,stroke:#8B0000,stroke-width:2px;
    classDef python fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef node fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef container fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef service fill:#DDA0DD,stroke:#800080,stroke-width:2px;
    classDef script fill:#FFE4B5,stroke:#CD853F,stroke-width:2px;
```
