# StorageIQ

StorageIQ is a modern Windows disk space analyzer built with Python and PySide6.

It scans drives or folders, summarizes storage usage, shows largest folders and files, groups usage by file type, and stores scan history in SQLite. File removal is intentionally limited to the Windows Recycle Bin and always requires confirmation.

Current release: **1.6.0**

## Features

- Scan full drives or custom folders
- Dashboard with polished storage, free space, scanned file/folder, and cleanup summary cards
- Storage Explorer interactive treemap with drill-down, breadcrumbs, search, filters, and detail actions
- Sortable largest folders and largest files views
- Global search with file category filters
- File type analysis chart with percentages and color legend
- AI Cleanup Advisor with rule-based, safety-first cleanup recommendations
- Duplicate Finder with staged size/hash detection and safe Recycle Bin cleanup
- Storage Timeline with historical charts, scan comparison, and growth insights
- Background scanning with progress and cancellation
- SQLite scan history with reopen support
- Safe file actions: open file, open containing folder, move to Recycle Bin
- Action logging in SQLite
- Crash-safe diagnostic logging to `%LOCALAPPDATA%\StorageIQ\logs\storageiq.log`
- Professional Windows installer framework with manual update checks, diagnostics center, and diagnostic bundles

## UI Polish

StorageIQ uses a modern dark interface with custom branding, a dedicated application icon, icon-led sidebar navigation, consistent spacing, stronger visual hierarchy, and dashboard cards designed for quick scanning. Empty-state screens guide first-time use, while the scan loading panel and status bar keep progress visible during long scans.

Tables use larger rows, clearer selection color, hover states, and reduced grid clutter. The Largest Files page surfaces direct action buttons for opening files, revealing folders, and moving files to the Recycle Bin, while unusually large files are visually highlighted.

## Duplicate Finder

StorageIQ v1.1 adds a Duplicate Finder page. It scans the selected drive or folder by grouping files by size first, then hashing only same-size candidates. Duplicate groups show filename, full path, size, modified date, and SHA-256 hash.

Cleanup remains safety-first: no files are selected automatically, the "Select Older Copies" helper keeps the newest copy in each group, "Recycle Selected" is disabled unless at least one copy remains in every duplicate group, and all cleanup actions are logged to SQLite.

## Storage Explorer

StorageIQ v1.6 adds Storage Explorer, an interactive treemap that turns scan results into an instant visual map of disk usage. Rectangles are sized by storage usage and colored by category: videos, images, archives, documents, executables, and other files.

Hover shows name, size, path, and type. Click selects an item, double-click drills into folders, and right-click opens file, folder, and detail actions. Breadcrumbs, Back, Home, search highlighting, category filters, and minimum-size filtering help users move through large scans quickly.

The treemap renders a virtualized visible subset of the scan snapshot so the UI remains responsive with large folders. Current scans keep up to 100,000 files and folders available for explorer navigation while existing tables remain focused on top results.

## Storage Timeline

StorageIQ v1.2 adds a Storage Timeline page that uses scan history snapshots to chart used space, free space, file count, and folder count over time. The page supports Last 7 Days, Last 30 Days, Last 90 Days, and All Time ranges.

Timeline comparison tools let users compare two scans to identify top growing and shrinking folders. Automatic insights summarize recent scan growth, dominant file type usage, and duplicate cleanup recovery when cleanup size details are available.

## AI Cleanup Advisor

StorageIQ v1.3 adds an AI Cleanup Advisor page. It is not a chatbot and does not send data to an AI service. The advisor uses local rules over scan results, duplicate finder results, file age, file size, file type, and scan history to surface prioritized cleanup opportunities.

Recommendation cards cover large files, old Downloads items, duplicate files, large videos, temporary files, compressed archives, and storage growth alerts. Actions remain manual: users can open files, open folders, view recommendation details, or jump to Duplicate Finder or Storage Timeline for deeper review.

Advisor thresholds for large files, old Downloads age, archive age, and video size can be adjusted from Settings.

## Deployment, Updates, and Diagnostics

StorageIQ v1.6 provides a professional Windows deployment foundation. `storageiq/version.py` is the central source for app name, version, build number, and build date. The app displays this information in the window title, About dialog, Diagnostics page, Settings page, logs, and installer metadata.

The Settings page includes theme selection, Stable/Beta release channel preference, default scan location, advisor thresholds, duplicate detection settings, a manual Check for Updates button, and a Generate Diagnostic Bundle action. Update checks compare the installed version with release metadata and display the current version, latest version, release date, release notes, and status. StorageIQ does not auto-download updates in v1.6.

The Diagnostics Center displays app version, build number, database location, log location, last scan date, historical scan count, duplicate cleanup action count, and advisor recommendation count. Diagnostic bundles are ZIP files containing logs, version info, environment info, configuration, and aggregate scan statistics. They intentionally exclude user files, scan file inventories, and personal documents.

Crash reports are written to `%LOCALAPPDATA%\StorageIQ\logs\crash_reports`. SQLite initialization includes migration backup protection and corrupt database quarantine/recreation so the app can start safely.

## Requirements

- Python 3.11+
- Windows 10/11

Install dependencies:

```powershell
python -m pip install -r requirements.txt
```

## Run

```powershell
python -m storageiq
```

The app database is stored at:

```text
%LOCALAPPDATA%\StorageIQ\storageiq.sqlite3
```

## Tests

```powershell
python -m unittest
```

## Build

```powershell
.\build.ps1
```

The PyInstaller output will be created in `dist\StorageIQ`. If Inno Setup 6 is installed and `ISCC.exe` is available on PATH, the Windows installer is created under `dist\installer`.

Installer source files live in `installer\`. The installer targets Program Files, creates Start Menu shortcuts, optionally creates a Desktop shortcut, registers an Add/Remove Programs uninstall entry, supports clean uninstall, and preserves user data during upgrades and uninstall under:

```text
%LOCALAPPDATA%\StorageIQ
```

Release notes and QA guidance:

- `RELEASE_NOTES.md`
- `docs\QA_CHECKLIST.md`
- `docs\INSTALLER_BUILD.md`

## Safety

StorageIQ never permanently deletes files. The only delete-like action is "Move to Recycle Bin", implemented with `send2trash`, after a confirmation dialog that displays the full path.
