Skip to content

Commit 3e50402

Browse files
TMHSDigitalTMHSDigital
committed
Initialize System Health Tool project with React frontend and Rust backend. Add essential files including .gitignore, package.json, and README. Implement core components for dashboard, disk cleanup, memory management, and startup management. Set up TypeScript and Vite for development. Include architecture and safety documentation.
0 parents  commit 3e50402

92 files changed

Lines changed: 17312 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
dist-ssr/
7+
8+
# Rust build output
9+
src-tauri/target/
10+
11+
# Environment & secrets
12+
.env
13+
.env.*
14+
*.local
15+
16+
# Logs
17+
logs/
18+
*.log
19+
npm-debug.log*
20+
yarn-debug.log*
21+
yarn-error.log*
22+
pnpm-debug.log*
23+
24+
# Editor directories and files
25+
.vscode/*
26+
!.vscode/extensions.json
27+
.idea/
28+
*.suo
29+
*.ntvs*
30+
*.njsproj
31+
*.sln
32+
*.sw?
33+
34+
# OS files
35+
.DS_Store
36+
Thumbs.db
37+
Desktop.ini
38+
39+
# Generated icon source (keep generated icons, not the source SVG)
40+
app-icon.svg

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 TMHSDigital
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
<div align="center">
2+
3+
# System Health Tool
4+
5+
**A lightweight Windows desktop app that scans, diagnoses, and cleans up system issues.**
6+
7+
Designed for people who aren't technical.
8+
9+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10+
[![Tauri](https://img.shields.io/badge/Tauri-2-blue?logo=tauri&logoColor=white)](https://v2.tauri.app)
11+
[![React](https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=white)](https://react.dev)
12+
[![Rust](https://img.shields.io/badge/Rust-Backend-orange?logo=rust&logoColor=white)](https://www.rust-lang.org)
13+
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
14+
15+
`2.5 MB installer` · `No bloat` · `No telemetry` · `Open source`
16+
17+
---
18+
19+
</div>
20+
21+
## Features
22+
23+
<table>
24+
<tr>
25+
<td width="50%">
26+
27+
### Dashboard
28+
Real-time health score (0–100), drive space bars, RAM usage donut chart, and a one-click **Quick Clean** button that only touches safe items.
29+
30+
</td>
31+
<td width="50%">
32+
33+
### Disk Cleanup
34+
Scans temp files, browser caches, crash dumps, dev caches, and the recycle bin. Every item has a color-coded risk label so you know exactly what's safe to delete.
35+
36+
</td>
37+
</tr>
38+
<tr>
39+
<td width="50%">
40+
41+
### Memory & Processes
42+
See what's eating your RAM, spot runaway processes, detect Hyper-V and WSL virtual machines hogging memory. Kill non-system processes directly.
43+
44+
</td>
45+
<td width="50%">
46+
47+
### Startup Manager
48+
Toggle startup programs on/off with impact ratings (High / Medium / Low) and "recommended to disable" badges. Nothing is uninstalled — just toggled.
49+
50+
</td>
51+
</tr>
52+
<tr>
53+
<td colspan="2">
54+
55+
### Smart Recommendations
56+
Auto-generated tips like *"Your pagefile is on a full drive"* or *"6 apps launch at startup"* — each with a **Fix It** button that navigates to the right panel.
57+
58+
</td>
59+
</tr>
60+
</table>
61+
62+
## Quick Start
63+
64+
### Download
65+
66+
Grab the latest installer from the [**Releases**](https://github.com/TMHSDigital/system-cleaner/releases) page:
67+
68+
| Format | Size | Notes |
69+
|--------|------|-------|
70+
| `System Cleaner_x.x.x_x64-setup.exe` | ~2.5 MB | NSIS installer (recommended) |
71+
| `System Cleaner_x.x.x_x64_en-US.msi` | ~3.8 MB | MSI installer |
72+
73+
Or grab the standalone `.exe` from the release — no install required.
74+
75+
> [!NOTE]
76+
> The app requests admin privileges on launch. This is needed for system-level operations like clearing Windows temp files, managing services, and reading all processes.
77+
78+
### Build From Source
79+
80+
**Prerequisites:** [Node.js](https://nodejs.org/) 18+ · [Rust](https://rustup.rs/) 1.85+ · Windows 10/11 with [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
81+
82+
```bash
83+
git clone https://github.com/TMHSDigital/system-cleaner.git
84+
cd system-cleaner
85+
npm install
86+
87+
# Dev mode (hot reload)
88+
npm run tauri:dev
89+
90+
# Production build
91+
npm run tauri:build
92+
```
93+
94+
Build output: `src-tauri/target/release/bundle/`
95+
96+
## Tech Stack
97+
98+
<div align="center">
99+
100+
| Layer | Technology |
101+
|-------|-----------|
102+
| **Frontend** | React 19 · TypeScript 5.9 · Tailwind CSS v4 · Recharts |
103+
| **Backend** | Tauri 2 (Rust) — native Win32 & registry access via `tauri::command` |
104+
| **Bundler** | Vite 7 |
105+
| **Icons** | Lucide React |
106+
107+
</div>
108+
109+
## Architecture
110+
111+
```
112+
┌─────────────────────────────────────────────────┐
113+
│ Tauri Window │
114+
│ ┌───────────────────────────────────────────┐ │
115+
│ │ React Frontend │ │
116+
│ │ Dashboard · Disk · Memory · Startup · Tips│ │
117+
│ │ ↕ api.ts │ │
118+
│ └───────────────────┬───────────────────────┘ │
119+
│ │ IPC (JSON) │
120+
│ ┌───────────────────┴───────────────────────┐ │
121+
│ │ Rust Backend (Tauri 2) │ │
122+
│ │ disk.rs · memory.rs · startup.rs │ │
123+
│ │ cleanup.rs · recommendations.rs │ │
124+
│ └───────────────────────────────────────────┘ │
125+
└──────────┬───────────────┬───────────────┬──────┘
126+
Win32 API PowerShell Registry
127+
```
128+
129+
> Full architecture docs: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
130+
131+
## Project Structure
132+
133+
```
134+
system-cleaner/
135+
├── src/ # React frontend
136+
│ ├── App.tsx # Sidebar nav + tab routing
137+
│ ├── components/
138+
│ │ ├── Dashboard.tsx # Health score, drives, RAM, Quick Clean
139+
│ │ ├── DiskCleanup.tsx # Scan → Review → Clean workflow
140+
│ │ ├── MemoryPanel.tsx # RAM chart, processes, VM detection
141+
│ │ ├── StartupManager.tsx # Toggle switches + impact ratings
142+
│ │ └── Recommendations.tsx # Auto-tips with Fix It navigation
143+
│ └── lib/
144+
│ ├── api.ts # Typed Tauri invoke() wrappers
145+
│ ├── types.ts # Shared interfaces
146+
│ └── format.ts # Byte/percent formatting
147+
├── src-tauri/ # Rust backend
148+
│ ├── src/
149+
│ │ ├── lib.rs # Tauri bootstrap + command registration
150+
│ │ ├── main.rs # Windows entry point
151+
│ │ └── commands/
152+
│ │ ├── disk.rs # Drive info, temp/cache/browser scanning
153+
│ │ ├── memory.rs # RAM stats, process list, VM detection
154+
│ │ ├── startup.rs # Registry + folder startup management
155+
│ │ ├── cleanup.rs # Safe deletion with progress tracking
156+
│ │ └── recommendations.rs
157+
│ ├── tauri.conf.json
158+
│ └── Cargo.toml
159+
├── docs/
160+
│ ├── ARCHITECTURE.md # How it works internally
161+
│ ├── SAFETY.md # Risk levels & what gets deleted
162+
│ └── CONTRIBUTING.md # How to contribute
163+
├── package.json
164+
├── vite.config.ts
165+
└── tsconfig.json
166+
```
167+
168+
## Safety
169+
170+
> [!IMPORTANT]
171+
> No files are ever deleted without showing you exactly what will happen first.
172+
173+
Every cleanable item is categorized by risk:
174+
175+
| Level | Color | Examples | What Happens |
176+
|-------|-------|----------|-------------|
177+
| **Safe** | Green | Temp files, browser caches, crash dumps | Always fine to delete — regenerated automatically |
178+
| **Moderate** | Yellow | Dev caches (npm, pip, cargo), Windows Update files | Re-downloaded when needed |
179+
| **Advanced** | Red | Reserved for future features | Requires explicit confirmation |
180+
181+
- **Quick Clean** only touches Safe items
182+
- Moderate/Advanced items must be manually checked in the Disk Cleanup tab
183+
- Locked files are silently skipped — no errors, no data loss
184+
- System processes cannot be killed from the Memory tab
185+
186+
> Full safety details: [`docs/SAFETY.md`](docs/SAFETY.md)
187+
188+
## Contributing
189+
190+
PRs welcome. See [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) for setup instructions, code style, and how to add new cleanup targets or recommendations.
191+
192+
```bash
193+
git clone https://github.com/TMHSDigital/system-cleaner.git
194+
cd system-cleaner && npm install
195+
npm run tauri:dev
196+
```
197+
198+
## License
199+
200+
[MIT](LICENSE)

‎app-icon.png‎

13.4 KB
Loading

‎docs/ARCHITECTURE.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
System Health Tool is a Tauri 2 desktop app: a Rust backend handles all system-level operations, and a React frontend provides the UI. They communicate via Tauri's `invoke()` IPC mechanism.
6+
7+
```
8+
┌─────────────────────────────────────────────────┐
9+
│ Tauri Window │
10+
│ ┌───────────────────────────────────────────┐ │
11+
│ │ React Frontend │ │
12+
│ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │
13+
│ │ │Dashboard│ │DiskClean │ │MemoryPanel│ │ │
14+
│ │ └────┬────┘ └────┬─────┘ └─────┬─────┘ │ │
15+
│ │ │ │ │ │ │
16+
│ │ ┌────┴───────────┴─────────────┴──────┐ │ │
17+
│ │ │ api.ts (invoke wrappers) │ │ │
18+
│ │ └────────────────┬────────────────────┘ │ │
19+
│ └───────────────────┼───────────────────────┘ │
20+
│ │ IPC (JSON serialization) │
21+
│ ┌───────────────────┼───────────────────────┐ │
22+
│ │ Rust Backend (Tauri) │ │
23+
│ │ ┌────────┐ ┌────────┐ ┌──────────────┐ │ │
24+
│ │ │disk.rs │ │memory │ │startup.rs │ │ │
25+
│ │ │ │ │ .rs │ │ │ │ │
26+
│ │ └────────┘ └────────┘ └──────────────┘ │ │
27+
│ │ ┌──────────┐ ┌─────────────────────┐ │ │
28+
│ │ │cleanup.rs│ │recommendations.rs │ │ │
29+
│ │ └──────────┘ └─────────────────────┘ │ │
30+
│ └───────────────────────────────────────────┘ │
31+
└─────────────────────────────────────────────────┘
32+
│ │ │
33+
Win32 API PowerShell Registry
34+
(disk space, (VM info, (startup
35+
processes) services) items)
36+
```
37+
38+
## Backend Commands
39+
40+
Each Rust module exposes `#[tauri::command]` functions that the frontend calls via `invoke()`.
41+
42+
### disk.rs
43+
44+
| Command | Returns | Description |
45+
|---|---|---|
46+
| `scan_disk()` | `DiskScanResult` | Scans all known cleanable locations, returns items with sizes and risk levels |
47+
| `get_drive_info()` | `Vec<DriveInfo>` | Enumerates all drives (A-Z) and returns total/free/used bytes via Win32 `GetDiskFreeSpaceExA` |
48+
49+
**Scan locations:** User temp, Windows temp, Recycle Bin, Chrome/Edge/Firefox cache, crash dumps, Windows Update downloads, thumbnail cache, npm/pip/cargo/nuget/go caches, log files.
50+
51+
Each item gets a risk classification:
52+
- `safe` — Always fine to delete (temp files, browser cache, crash dumps)
53+
- `moderate` — Will be re-downloaded when needed (dev caches, WU downloads)
54+
- `advanced` — Requires user judgment
55+
56+
### memory.rs
57+
58+
| Command | Returns | Description |
59+
|---|---|---|
60+
| `get_memory_info()` | `MemoryInfo` | Total/used/free RAM via `sysinfo` crate |
61+
| `get_processes()` | `Vec<ProcessInfo>` | Top 50 processes by RAM, with category labels and zombie detection |
62+
| `kill_process(pid)` | `Result<String>` | Terminates a process by PID |
63+
| `get_vm_info()` | `Vec<VmInfo>` | Detects Hyper-V VMs (via PowerShell `Get-VM`) and WSL distros (via `wsl --list`) |
64+
65+
**Zombie detection:** A process is flagged as a potential zombie if it uses >25% CPU but less than 10 MB RAM (indicating a busy-loop with no real work).
66+
67+
**Process categories:** Browser, Developer, Communication, Gaming, System, Other — determined by name matching.
68+
69+
### startup.rs
70+
71+
| Command | Returns | Description |
72+
|---|---|---|
73+
| `get_startup_items()` | `Vec<StartupItem>` | Reads from `HKCU\...\Run`, `HKLM\...\Run`, and the user's Startup folder |
74+
| `toggle_startup_item(id, enable)` | `Result<String>` | Enables/disables via `StartupApproved\Run` registry key or moving shortcut files |
75+
76+
**Impact estimation:** Based on known high-impact apps (Steam, Docker, OneDrive = High), medium-impact (Discord, NVIDIA, Corsair = Medium), everything else = Low.
77+
78+
**Recommended to disable:** Matches against a curated list of apps that are safe to not auto-start (Discord, Slack, Steam, Docker, Ollama, Figma, etc.).
79+
80+
### cleanup.rs
81+
82+
| Command | Returns | Description |
83+
|---|---|---|
84+
| `clean_items(item_ids, item_paths)` | `CleanupSummary` | Deletes selected items, returns per-item success/failure and total bytes freed |
85+
86+
Special handling:
87+
- **Recycle Bin** — Uses PowerShell `Clear-RecycleBin`
88+
- **Windows Update** — Stops `wuauserv` service before deleting, restarts after
89+
- **Memory dump** — Single file deletion
90+
- **Everything else** — Recursive directory content deletion, skipping locked files
91+
92+
### recommendations.rs
93+
94+
| Command | Returns | Description |
95+
|---|---|---|
96+
| `get_recommendations()` | `Vec<Recommendation>` | Analyzes current state and generates prioritized tips |
97+
98+
**Checks performed:**
99+
1. RAM usage > 85% → "Memory usage is very high"
100+
2. Any drive < 10% free → "Drive X is almost full"
101+
3. > 2 disableable startup items → "N programs launch at startup"
102+
4. Hyper-V VM memory > 3x startup and > 4 GB → "VM is using too much memory"
103+
5. > 1 GB cleanable junk → "Junk files detected"
104+
105+
## Frontend Components
106+
107+
### Dashboard.tsx
108+
Entry point. Loads drives, memory, and scan data in parallel. Shows health score (0-100) computed from RAM usage, disk free space, and junk file accumulation. Quick Clean button triggers safe-only cleanup.
109+
110+
### DiskCleanup.tsx
111+
Three-phase workflow: Scan → Review → Clean → Done. Items grouped by category (System, Browsers, Developer) with risk-colored badges. Checkboxes default to safe items selected.
112+
113+
### MemoryPanel.tsx
114+
RAM bar with color thresholds (green < 60%, yellow < 90%, red > 90%). Horizontal bar chart of memory by category. Process table with kill buttons (disabled for System category). VM detection section.
115+
116+
### StartupManager.tsx
117+
Toggle switches styled as iOS-like sliders. Warning banner when multiple items are recommended to disable. Impact badges (High/Medium/Low) with color coding.
118+
119+
### Recommendations.tsx
120+
Cards with severity-based styling (red border = high, yellow = medium, blue = low). Each card has a navigation button that jumps to the relevant tab.
121+
122+
## Data Flow
123+
124+
1. User opens app → Dashboard loads `getDriveInfo()`, `getMemoryInfo()`, `scanDisk()` in parallel
125+
2. Health score computed client-side from the combined data
126+
3. Quick Clean → filters scan results to `risk === "safe"` → calls `cleanItems()` → refreshes Dashboard
127+
4. Disk Cleanup tab → auto-scans on mount → user checks/unchecks items → Clean button → `cleanItems()` → shows results
128+
5. Memory tab → `getProcesses()` with 500ms delay between two `refresh_processes()` calls for accurate CPU measurement
129+
6. Startup tab → `getStartupItems()` → toggle calls `toggleStartupItem()` → optimistic UI update
130+
7. Recommendations → `getRecommendations()` which internally calls `scanDisk()`, `getStartupItems()`, checks VMs and drives

0 commit comments

Comments
 (0)