| # Computer Auditor — Features & Functionality | |
| Computer Auditor is a desktop **system inspection dashboard** for Windows, built with **Electron** and a **React + TypeScript** UI. It is styled like a **Task Manager / system manager** console: dark panels, dense tables, and icon-only actions with **hover labels** (custom tooltip plus native `title` for accessibility). | |
| The app is designed to **inventory and measure** what is on your machine—storage, processes, services, installed software, network, startup surface, scheduled automation, and optional Windows features—while letting you attach **persistent audit notes** to almost any entity you select. | |
| --- | |
| ## Platform & runtime | |
| - **Hybrid stack**: **React + TypeScript** UI (renderer), **Electron** main (IPC, notes, shell), and a **Python 3** **FastAPI** backend on **127.0.0.1** (dynamic port) for hot paths: directory listing with recursive sizes, folder totals, large-file scans, processes (`psutil`), drives (`psutil`), system/memory snapshot, environment, and network interfaces. Electron **spawns** `python -m uvicorn main:app` with cwd `backend/` and **kills** the process on quit. | |
| - **Windows-focused (Node)**: registry software list, services, scheduled tasks, DISM snapshot via **PowerShell** / `dism.exe`; Explorer and `taskkill` for actions. | |
| - **Python setup**: `cd backend && pip install -r requirements.txt`. Set **`PYTHON_PATH`** if `python` is not on `PATH`. | |
| - **Electron shell**: full local access from main; renderer is isolated (`contextIsolation`, no Node integration). | |
| - **Development**: `npm run dev` starts Vite and Electron together. **Production**: `npm run build` then `npm start`. | |
| --- | |
| ## User interface | |
| - **Minimal layout**: left **navigation rail** (icons + labels), main **toolbar** (section title, global refresh for live system snapshot, status line), scrollable **content**, and a fixed **notes** strip at the bottom. | |
| - **React Icons (`react-icons/md`)** for every actionable control; **hover** shows a text label via a small tooltip layer. | |
| - **No emoji** in the product chrome; data-first tables and monospace paths where helpful. | |
| - **Auto-refresh**: host memory and core **system snapshot** refresh on a short interval while the app is open (complementing manual refresh). | |
| --- | |
| ## Overview dashboard | |
| - **Host identity**: computer name, signed-in username context from Node. | |
| - **OS**: platform, kernel release, CPU architecture. | |
| - **Uptime**: human-readable uptime. | |
| - **Memory**: used vs total RAM, percentage, bar indicator. | |
| - **CPU**: logical processor count and model string from `os.cpus()`. | |
| - **Paths**: home directory and temp directory baselines. | |
| - **Quick actions** on this screen: | |
| - Load **logical volumes** (used/free/total per drive letter). | |
| - **Temp directory audit**: approximate total bytes and file count under temp paths (capped walk for safety/performance; may mark truncation when file cap hit). | |
| --- | |
| ## Storage & volumes | |
| - **Per-volume table**: device id (e.g. `C:`), volume label, used space, free space, total size, utilization bar. | |
| - **Open in Explorer** for a selected volume root. | |
| - **Notes** can be keyed to `drive:<letter>` for remediation tracking or change control. | |
| --- | |
| ## Folders & files | |
| - **Path bar**: type or paste any folder; **list contents** with a full recursive **byte total for every subfolder** (same capped walk as aggregate sizing: stops after a maximum **file count** so huge trees do not run forever). Sizes in the table are shown as **decimal KB** (1 KB = 1024 bytes, two fractional digits). If the cap is hit mid-folder, that row shows a **`+` suffix** (strict lower bound, not complete). | |
| - **Navigation**: parent shortcut, double-click to enter directories, **open in Explorer** for files or folders. | |
| - **Large file finder**: scan from a chosen root (defaults to current path) for files above a **minimum size in megabytes**; returns top hits sorted by size (result cap). Useful for reclaiming disk space or spotting bulky artifacts. | |
| - **Recursive folder size**: totals **bytes and file count** for the current path using a **capped** depth-first walk (stops after a maximum file count so system folders cannot lock the app). Shows whether the result was **truncated** due to the cap. | |
| - **Copy path**: copies the active folder path to the clipboard for tickets, scripts, or shell use (uses the browser clipboard API when available, otherwise **Electron’s clipboard** via IPC so it still works under `file://` loads). | |
| - **Notes** attach to `path:<fullPath>` keys. | |
| --- | |
| ## Processes | |
| - **Live process list** sourced from WMI/CIM (`Win32_Process`): PID, image name, working set (memory), coarse CPU time estimate (kernel + user time converted to seconds—useful for ordering, not a perf chart), and command line when available. | |
| - **Filter** by name, PID, or command line substring. | |
| - **End process**: invokes `taskkill /F` after an explicit confirmation. This is a **destructive** action; data in that process may be lost. | |
| - **Notes** per `proc:<pid>` (PID can change across reboots; notes remain as historical annotations unless you clear them). | |
| --- | |
| ## Services | |
| - **Windows services** via `Win32_Service`: internal name, display name, state (running/stopped/etc.), start mode (auto/manual/disabled, etc.). | |
| - **Filtering** across name, display name, and state. | |
| - **Notes** per `svc:<service name>`. | |
| > The app **does not** start/stop/reconfigure services from the UI (that would require elevated privileges and careful safety). It is **audit and documentation** first. | |
| --- | |
| ## Installed software | |
| - **Add/remove programs style inventory** from registry hives (64-bit, 32-bit WOW6432Node, and per-user uninstall keys) via PowerShell `Get-ItemProperty`. | |
| - Columns include **name, version, publisher, install location, estimated size** (when publishers populate it), and raw uninstall string (for your runbooks). | |
| - **Open install folder** when a path exists. | |
| - **Notes** per `app:<display name>` (names are not guaranteed unique if vendors collide; use notes carefully). | |
| --- | |
| ## Network | |
| - **Logical interfaces** from `os.networkInterfaces()`: addresses, address family, internal flag, MAC when present. | |
| - **Notes** per `net:<interface>:<address>` to document VLANs, VPNs, or static assignments. | |
| --- | |
| ## Environment | |
| - **Full process environment block** as read by the Electron main process (sorted `KEY=value` lines). Useful for spotting **mis-set PATH**, proxy variables, or deployment tooling flags. | |
| - **Note** slot `env:all` for global remarks about environment hygiene. | |
| --- | |
| ## Startup items | |
| - Scans **per-user** and **all-users** Startup shell folders (shortcuts and files). Lists name, type, and allows **Explorer** jump and **path notes** for each entry. | |
| --- | |
| ## Scheduled tasks | |
| - Enumerates **Task Scheduler** tasks with **name** and **state** via `Get-ScheduledTask` (PowerShell). Handy for **persistence hunting** and automation audits. | |
| - **Notes** per `task:<task name>`. | |
| --- | |
| ## Windows optional features (DISM) | |
| - Pulls a **truncated text table** from `dism /Online /Get-Features /Format:Table` for an offline-friendly snapshot of **optional Windows features** state. Large output is clipped to keep IPC responsive; use **note** `features:snippet` to record interpretation or follow-up. | |
| --- | |
| ## Notes system | |
| - **Persistent JSON** store under the app’s **Electron `userData`** directory (`auditor-notes.json`). | |
| - **Key/value** model: keys are semantic strings (`path:…`, `proc:…`, `drive:…`, etc.). | |
| - **Save**, **clear** (delete key), and **reload** from disk. | |
| - Selecting an entity from a table or drive row sets the **active note key**; the footer editor binds to that key. | |
| --- | |
| ## Cross-cutting actions | |
| - **Open in Explorer** for paths and volumes (`explorer.exe`). | |
| - **Open external URL** hook exists in the main process for future deep links (IPC wired). | |
| - **Status and error lines** in the toolbar for long operations (process list, services, DISM, large scans). | |
| --- | |
| ## Safety, performance, and limitations | |
| - **Heavy filesystem and process enumeration** run in the **Python** process over **HTTP** (FastAPI + `psutil` + threaded `os.walk` / `os.scandir`), so the Electron **main** thread only proxies `fetch` and stays responsive. | |
| - **Directory walks** and **large-file scans** use **caps** (max files, max depth, max results) so accidental scans of entire drives do not run unbounded; results may be **partial** or **truncated**—always stated where relevant. | |
| - **Administrator elevation** is **not** assumed. Some counters (certain services, protected paths) may be incomplete without elevation; DISM feature enumeration may require an elevated session on some systems. | |
| - **Process kill** and **Explorer open** are the main **active** interventions; everything else is **read/audit**. | |
| - **Non-Windows** platforms are not the target: several modules will return empty or fallback data if ported without adapters. | |
| --- | |
| ## How it fits together | |
| 1. **Python** (`backend/main.py`): FastAPI on localhost; parallel folder sizing via `ThreadPoolExecutor`; process/disk/network/env data via `psutil`. | |
| 2. **Main process** (`electron/`): starts/stops Python, proxies audit calls with `fetch`, handles notes JSON, PowerShell-only features, Explorer, `taskkill`. | |
| 3. **Preload** exposes **`window.auditor`** (IPC). | |
| 4. **Renderer** (`src/`): React + TypeScript—**no** Python or Node builtins. | |
| This split keeps the UI responsive while still allowing **deep system visibility** appropriate for a personal or IT **audit workstation** tool. | |