jessey
305b6c4497
Planning docs (SPEC, ARCHITECTURE, MODULES, ROADMAP, DECISIONS) with decisions D1-D15 settled: RigDoctor name, Python 3 + Qt/PySide6 stack (core/CLI/daemon stdlib-only), Ubuntu + NVIDIA first, .deb packaging, read-only + suggestions, GUI + tray modules, stress module dropped. First code: the M1 sensor core (stdlib-only) and a CLI. - core engine: Reading/Sample model, Sampler, hwmon reader - self-probing sources (NVIDIA first): nvidia-smi GPU, coretemp/k10temp CPU, /proc/meminfo + DDR5 SPD memory, NVMe storage - CLI: snapshot (text/JSON), monitor, sources; record/report stubbed - stdlib unittest smoke tests Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# RigDoctor
|
||
|
||
A **modular diagnostics, monitoring, and health-check toolkit for Linux gamers.**
|
||
|
||
> **Status:** 🟢 Phase 1 (MVP) in progress. Foundational decisions are settled and the
|
||
> **sensor core (M1)** works — `snapshot` / `monitor` read NVIDIA GPU, CPU, memory, and
|
||
> NVMe live. Crash logger (M3) and health report (M4) are next. See `docs/ROADMAP.md`.
|
||
|
||
## Why this exists
|
||
|
||
Linux gaming hardware faults are hard to diagnose: GPUs falling off the PCIe bus, the screen
|
||
suddenly going black mid-game, silent thermal/VRAM throttling, power transients,
|
||
driver/library mismatches, Proton quirks, and CPU governor / power-profile misconfiguration.
|
||
The data needed to diagnose them is scattered across `nvidia-smi`, `/sys/class/hwmon`,
|
||
`journalctl`, SMART, and more — and the most useful readings (the ones right before a hard
|
||
freeze) are usually lost because nothing flushed them to disk.
|
||
|
||
RigDoctor pulls all of that into one modular tool: live monitoring, crash-safe logging, a
|
||
one-shot health report, and an interactive installer that only sets up the modules a given
|
||
user actually needs for their hardware.
|
||
|
||
**Seed use cases:** an RTX 3070 that intermittently "falls off the bus" under heavy GPU load
|
||
(Path of Exile on Linux, Escape from Tarkov on Windows), and a monitor going black mid-game.
|
||
See `docs/SPEC.md` §1.
|
||
|
||
## How you run it
|
||
|
||
Three front-ends over one shared engine — pick what fits:
|
||
- **CLI / headless** — full functionality from the terminal, works over SSH.
|
||
- **Desktop GUI** — graphical dashboard, log browser, and health-report viewer.
|
||
- **Tray applet** — a small applet in the top menu bar with quick actions (e.g. start
|
||
recording) and at-a-glance status.
|
||
|
||
The GUI and tray are optional modules; a headless install loses no diagnostic capability.
|
||
|
||
## Key decisions (settled)
|
||
|
||
| Topic | Decision |
|
||
|-------|----------|
|
||
| Name | **RigDoctor** |
|
||
| Language / stack | **Python 3 + Qt (PySide6)** — core/CLI/daemon stdlib-only; Qt only for GUI/tray |
|
||
| Primary distro | **Ubuntu** (Debian via apt); others best-effort later |
|
||
| Primary GPU | **NVIDIA** first; AMD, then Intel later |
|
||
| MVP | **Sensor core + crash logger + health report** (NVIDIA-only, CLI-first) |
|
||
| Distribution | **`.deb`** + interactive module installer |
|
||
| Scope of action | **Read-only + suggestions** (no auto-apply yet) |
|
||
| Stress tests | **Out of scope** |
|
||
|
||
Full rationale and the still-open questions are in `docs/DECISIONS.md`.
|
||
|
||
## Repo layout
|
||
|
||
| Path | Purpose |
|
||
|------|---------|
|
||
| `docs/SPEC.md` | Product specification — vision, requirements, modules (the main planning doc) |
|
||
| `docs/ARCHITECTURE.md` | Technical design — core engine, front-ends, daemon, installer |
|
||
| `docs/MODULES.md` | Catalog of modules with scope, dependencies, status |
|
||
| `docs/ROADMAP.md` | Phased milestones |
|
||
| `docs/DECISIONS.md` | Decision log + remaining open questions |
|
||
| `src/rigdoctor/` | Source code — `core/` engine + sources, `cli.py`, `render.py` |
|
||
| `installer/` | Installer / `.deb` packaging (empty until Phase 4) |
|
||
| `tests/` | Tests (stdlib `unittest`) |
|
||
|
||
## Run it (dev)
|
||
|
||
Stdlib-only, no install needed (target is Python ≥ 3.11; tested on 3.14):
|
||
|
||
```bash
|
||
PYTHONPATH=src python3 -m rigdoctor snapshot # one-shot sensor read
|
||
PYTHONPATH=src python3 -m rigdoctor snapshot --json
|
||
PYTHONPATH=src python3 -m rigdoctor monitor -n 1 # live view (Ctrl-C to quit)
|
||
PYTHONPATH=src python3 -m rigdoctor sources # list detected sensor sources
|
||
PYTHONPATH=src python3 -m unittest discover -s tests
|
||
```
|
||
|
||
Or `pip install -e .` to get a `rigdoctor` command on your PATH.
|
||
|
||
## Start here
|
||
|
||
1. Read `docs/SPEC.md` for what we're building.
|
||
2. Read `docs/ROADMAP.md` for the build order (Phase 1 = the MVP).
|
||
3. Read `docs/DECISIONS.md` for the settled decisions (D1–D15).
|
||
</content>
|