# smare/rpi_server_stats architecture

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

- Interactive diagram: https://gitdiagram.com/smare/rpi_server_stats
- Repository: https://github.com/smare/rpi_server_stats

## Overview

##### Project Type and Purpose
- This is an open-source utility for Raspberry Pi devices that collects OS statistics (CPU, memory, disk, network, etc.) and renders them on an attached ST7789 display.
- It provides two parallel setups: one for Raspberry Pi 5+ (`run_rpi5_stats_ST7789.py` + `prerequisites-run_rpi5_stats_ST7789.sh` + `doc/rpi5/`) and one for Raspberry Pi 4 and older (`run_rpi_stats_ST7789.py` + `prerequisites-run_rpi_stats_ST7789.sh` + `doc/rpi/`).

##### File Structure
- Top level:
- `README.md` – project overview
- `doc/rpi` & `doc/rpi5` – hardware-specific setup instructions
- Shell scripts (`prerequisites-*.sh`) – install dependencies (Python libraries, SPI drivers, etc.)
- Python scripts (`run_*.py`) – collect stats & drive the ST7789 display
- No database or web server – it’s a single‐device, script‐driven tool.
- Uses hardware SPI (or bit-banged GPIO) to drive the ST7789 display.

##### README for Additional Insights
- Clarifies supported Pi models and links to hardware‐specific docs.
- Implies use of standard system‐metric libraries (e.g., `psutil` in Python) and low‐level SPI display drivers.

##### Main Components to Model
a. Hardware Layer
- Raspberry Pi board (BCM SoC + Linux OS)
- ST7789 display module (connected over SPI/GPIO)
b. Software Layer
- Prerequisite installer script (shell script)
- Python stats-collector & display renderer
- Underlying libraries:
- OS stats library (e.g., `psutil`)
- SPI/display driver (e.g., `luma.lcd` or direct `spidev`)
c. Documentation
- `doc/rpi` and `doc/rpi5` as user-facing setup guides

##### Relationships and Data Flows
- Data flow:
1. Shell script installs Python, pip packages, SPI kernel modules.
2. Python script reads OS metrics via `psutil`.
3. Script formats metrics into text/graphics.
4. Script sends pixel/command frames over SPI to ST7789.
5. Module renders the frame.
- OS kernel → Python stats library
- Python application → SPI driver → ST7789 hardware
- Shell script → OS package manager

##### Architectural Patterns and Principles
- Single‐process application pattern (no multi-service or microservices).
- Clear separation:
- Setup phase (shell script) vs. runtime phase (Python script).
- Metric-collection vs. rendering logic.
- Extensibility point: adding support for new display types by swapping the rendering driver.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Documentation"
        README["Project Overview (README.md)"]:::docs
        RPI4_DOC["RPi4 and older Docs (doc/rpi/README.md)"]:::docs
        RPI5_DOC["RPi5+ Docs (doc/rpi5/README.md)"]:::docs
    end

    subgraph "Setup Phase"
        INSTALL_SCRIPT_RPI4["Installer Script RPi4 (prerequisites-run_rpi_stats_ST7789.sh)"]:::scripts
        INSTALL_SCRIPT_RPI5["Installer Script RPi5 (prerequisites-run_rpi5_stats_ST7789.sh)"]:::scripts
        OS["OS Kernel & Package Manager"]:::os
    end

    subgraph "Runtime Phase"
        subgraph "Python Application"
            PYTHON_APP_RPI4["Runtime App RPi4 (run_rpi_stats_ST7789.py)"]:::python
            PYTHON_APP_RPI5["Runtime App RPi5 (run_rpi5_stats_ST7789.py)"]:::python
            PSUTIL["OS Stats Library (psutil)"]:::python
            SPI_DRV["SPI Display Driver (luma.lcd / spidev)"]:::python
        end
    end

    DISPLAY["ST7789 Display"]:::hardware

    %% Documentation flow
    README --> RPI4_DOC
    README --> RPI5_DOC
    RPI4_DOC --> INSTALL_SCRIPT_RPI4
    RPI5_DOC --> INSTALL_SCRIPT_RPI5

    %% Setup flow
    INSTALL_SCRIPT_RPI4 -->|"installs packages & SPI modules"| OS
    INSTALL_SCRIPT_RPI5 -->|"installs packages & SPI modules"| OS

    %% Runtime flow
    OS -->|"provides runtime environment"| PYTHON_APP_RPI4
    OS -->|"provides runtime environment"| PYTHON_APP_RPI5
    PYTHON_APP_RPI4 -->|"uses psutil API"| PSUTIL
    PYTHON_APP_RPI5 -->|"uses psutil API"| PSUTIL
    PYTHON_APP_RPI4 -->|"uses SPI driver"| SPI_DRV
    PYTHON_APP_RPI5 -->|"uses SPI driver"| SPI_DRV
    SPI_DRV -->|"SPI / GPIO"| DISPLAY

    %% Click Events
    click README "https://github.com/smare/rpi_server_stats/blob/main/README.md"
    click RPI4_DOC "https://github.com/smare/rpi_server_stats/blob/main/doc/rpi/README.md"
    click RPI5_DOC "https://github.com/smare/rpi_server_stats/blob/main/doc/rpi5/README.md"
    click INSTALL_SCRIPT_RPI4 "https://github.com/smare/rpi_server_stats/blob/main/prerequisites-run_rpi_stats_ST7789.sh"
    click INSTALL_SCRIPT_RPI5 "https://github.com/smare/rpi_server_stats/blob/main/prerequisites-run_rpi5_stats_ST7789.sh"
    click PYTHON_APP_RPI4 "https://github.com/smare/rpi_server_stats/blob/main/run_rpi_stats_ST7789.py"
    click PYTHON_APP_RPI5 "https://github.com/smare/rpi_server_stats/blob/main/run_rpi5_stats_ST7789.py"

    %% Styles
    classDef docs fill:#aaccff,stroke:#333,stroke-width:1px
    classDef scripts fill:#aaccff,stroke:#333,stroke-width:1px
    classDef python fill:#aaccff,stroke:#333,stroke-width:1px
    classDef os fill:#cccccc,stroke:#333,stroke-width:1px
    classDef hardware fill:#aaffaa,stroke:#333,stroke-width:1px
```
