CHIT THWAY
Storage Insights and Guided Cleanup demonstration43 second demonstration
Projects

Windows support extension

Storage Insights & Guided Cleanup

A local storage-analysis and guided-cleanup extension that turns a broad disk-space warning into clear evidence, focused review and deliberately recoverable action.

View repository
View extension branch
Status
Extension complete
Environment
Windows / local only
Analysis
Metadata only
Cleanup
Recycle Bin only

The process

How this extension grew

  1. Initial Problem

    A warning without a next step

    The diagnostic dashboard could identify low disk space, but it could not show where the space had gone or help the user decide what to review next.

  2. First idea

    Find old files

    Scan file metadata, mark anything unchanged for 730 days as Stale, identify large, empty, temporary or incomplete files, and let the user filter candidates for reviewed Recycle Bin cleanup.

  3. Result

    The age-led prototype worked

    The first extension produced metadata-only reports, displayed candidate files, supported Match all and Match any filtering, and added an exact-path preview before moving selected eligible files to the Recycle Bin.

  4. Problem

    Old did not mean disposable

    An untouched file could still be a game save, configuration, installer, database, application asset or personal archive. Modification age explained when something changed—not whether it remained important.

  5. Solution

    Separate clues from permission

    Candidate evidence, technical eligibility and removal risk became separate concepts. High-risk application data, saves, installers, databases, configuration files and protected locations remained visible but could not be selected.

  6. Problem

    The totals were misleading

    Logical file length did not always equal physical disk use. Hard links could be counted more than once, inaccessible space remained unknown and bounded candidate rows could hide important files.

  7. Solution

    Measure physical use properly

    The scanner adopted Windows allocated-size metadata, stable file identities for hard-link deduplication, explicit unclassified space and deterministic retention favouring physically larger and safer candidates.

  8. Problem

    Folders made everything harder

    Grouping files into folders reduced the number of rows, but parent and child totals overlapped, stale folders repeated evidence, and one changed or inaccessible descendant could invalidate an action.

  9. Solution

    Harden the folder experiment

    Equivalent stale chains were collapsed, overlapping parent-and-child selections were rejected, risky trees became review-only, and every descendant was revalidated using a metadata-only fingerprint.

  10. Problem

    It was still the wrong question

    Even after extensive safeguards, the workflow still centred on which old files could be removed. That remained uncertain and did not help users explore storage through things they recognized.

  11. Unexpected idea

    Solution

    Pivot to file types

    The project became a File-Type Explorer: scan each drive once, group recognizable extensions, rank folders by matching content, choose non-overlapping scopes and inspect exact files without treating age as permission.

  12. Problem

    Filtering could not rescan the drive

    A whole-drive traversal could be slow or partial. Repeating it whenever the user selected Documents, Videos, Archives or another extension group would make the explorer impractical.

  13. Solution

    Scan once, filter many times

    A separate per-drive index stores exact folder and preset-extension aggregates from one metadata-only traversal. File details can remain bounded while filters and ranked folder totals stay truthful without another scan.

  14. Result

    A review system, not a cleaner

    The final extension helps users understand storage by familiar file types, narrow the search to exact folders and files, and move only explicitly reviewed, unchanged, eligible items to the Recycle Bin.

  15. Lesson

    Guardrails cannot fix the wrong model

    The age-led version grew increasingly complicated as protections were added. The stronger solution came from changing the organizing idea—from predicting disposability to helping users explore recognizable evidence.

Technology architecture

Storage Insights & Guided Cleanup

Local storage evidence and guarded cleanup workflow

Analysis

  • Python
  • Windows

Interface

  • Flask
  • HTML
  • CSS
  • JavaScript

Contracts

  • JSON Schema
  • Versioned reports

Quality

  • Pytest
  • Safety validation

Explicit Python scanners produce validated local reports for a loopback-only Flask interface, while deterministic policy and immediate revalidation guard every cleanup action.

Overview / 01

What the project demonstrates

Storage Insights extends the diagnostic toolkit beyond a simple low-space warning. An explicitly started scanner records local file metadata, drive capacity, coverage and inaccessible paths, then presents non-overlapping categories that explain where physical drive space is being used without pretending partial evidence is complete.

The dashboard supports individual-file, folder and file-type exploration. Stored aggregates let filters and ranked folders update without silently rescanning the drive, while protected locations, review-only items and incomplete coverage remain visible instead of being simplified into unsafe cleanup recommendations.

Selecting an item changes nothing. Cleanup requires a separate exact-path preview and explicit confirmation, followed by immediate checks of scope, metadata, risk and reparse-point state. Eligible unchanged items are sent to the Windows Recycle Bin; permanent deletion is never used as a fallback.

Try it / 02

A simple first run

This example analyses one drive. Replace C:\ with the drive you want to review; repeat it with different output names only when you need another drive.

You will need
  • Windows PowerShell 5.1
  • Python 3.10+
  • Git or a downloaded repository ZIP
  1. 01

    Set up the project once

    Open PowerShell in the downloaded project folder, then create the local environment and install its requirements.

    python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
  2. 02

    Generate the three local reports

    Create the Windows report, storage analysis and File-Type Explorer index. Change C:\ to the drive you want to inspect.

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File '.\collector\Collect-Diagnostics.ps1' -OutputPath '.\reports\first-report.json'
python -m storage --root 'C:\' --output 'selected-drive-report.json'
python -m storage.file_type_indexer --drive 'C:\' --output 'selected-drive-file-types.json'
  3. 03

    Open everything together

    Start the private local dashboard with the three reports you just created, then open the local address shown in PowerShell.

    python -m dashboard --report '.\reports\first-report.json' --storage-report '.\storage-reports\selected-drive-report.json' --file-type-index '.\storage-reports\selected-drive-file-types.json'
http://127.0.0.1:5000

Thinking / 03

Decisions behind the work

01

Make every scan explicit

The dashboard never starts a filesystem scan silently. Users select the roots and run the scanner themselves, keeping scope and cost visible.

02

Keep the accounting honest

Drive categories do not overlap, partial scans disclose their limits and folder hierarchy totals are never misrepresented as uniquely recoverable physical space.

03

Separate review from action

Filters, selections and previews remain read-only. Cleanup requires another confirmation and live revalidation before Windows receives a Recycle Bin request.

04

Fail toward safety

Protected paths, reparse points, changed files, review-only risks and incomplete evidence disable cleanup rather than being treated as permission to proceed.

Evidence / 04

Skills and capabilities

  • Non-overlapping drive-space accounting
  • File-type and ranked-folder exploration
  • Revalidated Recycle Bin-only cleanup
  • Python
  • Flask
  • JavaScript
  • JSON Schema
  • Pytest
  • Windows

This extension analyses local metadata and supports guided review; it does not claim that an old or large item is safe to remove. Recycle Bin recovery remains controlled by Windows.