# diffstorm/processwatchdog architecture

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

- Interactive diagram: https://gitdiagram.com/diffstorm/processwatchdog
- Repository: https://github.com/diffstorm/processwatchdog

## Overview

##### Project type and purpose
- This is a Linux-based, single-binary “daemon” utility (Process Watchdog) written in C.
- Its job is to read a list of applications from an INI file, start them with delays, monitor their health via UDP heartbeats (or simple liveness checks), restart any that hang or crash, and maintain statistics and a file-based command interface.

##### File structure
- Top-level:
- config.ini – declarative process list and UDP port
- run.sh – wrapper to relaunch the watchdog if it crashes
- Makefile – build script
- src/ – modular C source:
- ini.c/h – parse config.ini
- server.c/h – UDP listener and dispatcher
- apps.c/h – process-start/stop abstractions
- filecmd.c/h – file-based command interface (wdtstop, etc.)
- stats.c/h – statistics gathering & log file writer
- log.c/h – internal logging
- utils.c/h – shared utilities
- main.c – orchestration
- test.c/h – unit-test harness
- test_child.py – a Python script used by the example config to simulate child processes (heartbeat/no-heartbeat modes)

##### Extract key architectural points from the README
- Reads an INI file with N “apps”, each with start_delay, heartbeat_interval, cmd
- Opens a UDP socket on configured port, listens for “p< PID>” heartbeats
- Tracks last-heartbeat timestamps; if overdue, kills & restarts the process
- Provides file commands for manual control (startN, stopN, wdtstop, etc.)
- Writes per-app statistics to log files

a. Configuration Loader
– parses config.ini on startup
b. Process Manager
– spawns child processes (via `apps.c`)
– tracks PIDs, start/stop logic
c. Heartbeat Server (UDP Listener)
– binds to UDP port (server.c)
– dispatches heartbeat events to Process Manager
d. Watchdog Controller (main loop)
– enforces start_delay, heartbeat_delay, restart logic
– invokes filecmd module on detecting command files
e. File-Command Interface
– polls a directory or watches files (filecmd.c), translates files to control events
f. Statistics Logger
– collects metrics (start count, heartbeat stats) and writes to disk via log.c/stats.c
g. OS / External Environment
– Linux process API, signals, sockets
– File system (config, control files, log files)
h. Managed Applications
– arbitrary executables or scripts (e.g., test_child.py)

##### Interactions & data flow
1. On launch, the Watchdog Controller loads config.ini via Configuration Loader.
2. According to start_delay, the Process Manager forks/execs each app’s cmd.
3. Child processes send UDP heartbeats to the UDP port.
4. Heartbeat Server receives packets, extracts PID, notifies Watchdog Controller / Process Manager.
5. Watchdog Controller compares timestamps, decides if a process needs restart.
6. On restart, Process Manager kills old PID (if needed) and respawns via apps module.
7. File-Command Interface scans for “wdtstop”, “start2”, etc., instructs Watchdog Controller.
8. Statistics Logger records events (starts, crashes, heartbeat timing) to log files.

##### Architectural patterns & principles
- Modular layering: config parsing → core controller → I/O modules (UDP, FS) → process management → logging
- Event-driven: heartbeat arrival and file commands trigger actions
- Single responsibility: each C module handles one domain (INI, UDP, file cmd, logging)
- Config-driven behavior: no hard-coded processes, all managed entities defined in INI

##### Technologies & libraries
- C standard library, POSIX API (fork/exec, signals)
- BSD sockets for UDP
- Custom lightweight INI parser
- Shell script (run.sh) for resilience
- Python (test_child.py) for demo clients

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Watchdog Daemon"
        subgraph "I/O Modules"
            ConfigLoader["Configuration Loader"]:::io
            HeartbeatServer["Heartbeat Server (UDP)"]:::io
            FileCmd["File-Command Interface"]:::io
        end
        subgraph "Core Controller"
            Controller["Watchdog Controller"]:::core
            ProcessMgr["Process Manager"]:::core
        end
        StatisticsLogger["Statistics Logger"]:::io
        InternalLog["Internal Logging Module"]:::io
        UnitTest["Unit-Test Harness"]:::test
    end

    subgraph "External Environment"
        OS["Linux OS & File System"]:::ext
        ManagedApp["Managed Applications"]:::ext
        runSH["run.sh"]:::ext
        MakefileNode["Makefile"]:::ext
        Pro["processWatchdog.pro"]:::ext
        Docs["Documentation & CI"]:::ext
    end

    subgraph "Data Stores"
        configIni["config.ini"]:::data
        CommandFiles["Command Files"]:::data
        LogFiles["Log Files"]:::data
    end

    configIni -->|"parsed INI"| ConfigLoader
    ConfigLoader -->|config| Controller
    Controller -->|start/stop| ProcessMgr
    ProcessMgr -->|fork/exec| OS
    ManagedApp -->|UDP heartbeat| HeartbeatServer
    HeartbeatServer -->|p<PID>| Controller
    Controller -->|restart if needed| ProcessMgr
    OS -->|file events| FileCmd
    CommandFiles --> FileCmd
    FileCmd -->|commands| Controller
    Controller -->|metrics| StatisticsLogger
    StatisticsLogger --> LogFiles
    Controller -->|logs| InternalLog
    ProcessMgr -->|logs| InternalLog
    StatisticsLogger -->|logs| InternalLog
    FileCmd -->|logs| InternalLog
    runSH -.->|monitors| Controller
    MakefileNode -.->|builds| Controller
    Pro -.->|project config| Controller
    Docs -.->|guides & CI| Controller

    click ConfigLoader "https://github.com/diffstorm/processwatchdog/blob/main/src/ini.c"
    click ConfigLoader "https://github.com/diffstorm/processwatchdog/blob/main/src/ini.h"
    click HeartbeatServer "https://github.com/diffstorm/processwatchdog/blob/main/src/server.c"
    click HeartbeatServer "https://github.com/diffstorm/processwatchdog/blob/main/src/server.h"
    click FileCmd "https://github.com/diffstorm/processwatchdog/blob/main/src/filecmd.c"
    click FileCmd "https://github.com/diffstorm/processwatchdog/blob/main/src/filecmd.h"
    click Controller "https://github.com/diffstorm/processwatchdog/blob/main/src/main.c"
    click Controller "https://github.com/diffstorm/processwatchdog/blob/main/src/utils.c"
    click Controller "https://github.com/diffstorm/processwatchdog/blob/main/src/utils.h"
    click ProcessMgr "https://github.com/diffstorm/processwatchdog/blob/main/src/apps.c"
    click ProcessMgr "https://github.com/diffstorm/processwatchdog/blob/main/src/apps.h"
    click StatisticsLogger "https://github.com/diffstorm/processwatchdog/blob/main/src/stats.c"
    click StatisticsLogger "https://github.com/diffstorm/processwatchdog/blob/main/src/stats.h"
    click InternalLog "https://github.com/diffstorm/processwatchdog/blob/main/src/log.c"
    click InternalLog "https://github.com/diffstorm/processwatchdog/blob/main/src/log.h"
    click UnitTest "https://github.com/diffstorm/processwatchdog/blob/main/src/test.c"
    click UnitTest "https://github.com/diffstorm/processwatchdog/blob/main/src/test.h"
    click runSH "https://github.com/diffstorm/processwatchdog/blob/main/run.sh"
    click ManagedApp "https://github.com/diffstorm/processwatchdog/blob/main/test_child.py"
    click MakefileNode "https://github.com/diffstorm/processwatchdog/tree/main/Makefile"
    click Pro "https://github.com/diffstorm/processwatchdog/blob/main/processWatchdog.pro"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/README.md"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/.github/workflows/c-cpp.yml"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/.gitignore"
    click Docs "https://github.com/diffstorm/processwatchdog/tree/main/LICENSE"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/CONTRIBUTING.md"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/CODE_OF_CONDUCT.md"
    click Docs "https://github.com/diffstorm/processwatchdog/blob/main/CHANGELOG.md"

    classDef core fill:#c8e6c9,stroke:#333
    classDef io fill:#bbdefb,stroke:#333
    classDef ext fill:#ffe0b2,stroke:#333
    classDef data fill:#eeeeee,stroke:#333
    classDef test fill:#e1bee7,stroke:#333
```
