Win11OptDoctor (win11opt)

Win11OptDoctor — The Recovery Doctor for Failed Optimizations
Curing Windows 11 systems damaged by aggressive third-party debloaters & restoring standard stability.

📖 Read in Traditional Chinese / 繁體中文說明文件

---

🌟 Key Features

• Hardware Auto-Detection & Adaptive Rules:
  • SysMain (Superfetch): Explains why keeping SysMain enabled caches apps 2x-5x faster based on detected RAM capacity.
  • Pagefile (Virtual Memory): Maintains auto-managed virtual memory to prevent Chrome & heavy app crashes.
  • SSD Trim (defragsvc): Preserves SSD scheduled optimization to maximize SSD lifespan.
• Adaptive Usage Scenarios:
  • Default (Office/Daily): Balanced stability, security, and responsiveness.
  • Gaming Mode: Maximizes foreground CPU priority & network responsiveness, disables indexing overhead.
  • Privacy Mode: Disables background telemetry, appraiser tasks, and diagnostic packet routing.
• Two-Phase Repair Workflow:
  • Phase 1 (Diagnostic Checklist): Clear side-by-side comparison of turning each setting ON vs OFF.
  • Phase 2 (Confirmation & Apply): Review checklist with safety checks before applying system modifications.
• Ultra-Fast Parallel Scanning (<1s):
  • Bulk service query engine & native C Win32 API (GlobalMemoryStatusEx) reduce diagnostic latency from 20s to under 1 second.
• Full I18n & Internationalization:
  • Seamless real-time toggle between English and Traditional Chinese (zh-TW).
• Real-time RAM & Top Memory Hogs:
  • Groups multi-process applications (e.g. Chrome tabs) into Top 5 Memory Hogs with real-time RAM usage gauges.
• Windows Event Viewer Crash Analyzer:
  • Direct insight into recent System and Application Error/Critical crash logs with error ID parsing.
• Triple Reversibility Safety Net:
  • Automated Windows System Restore Point creation (Checkpoint-Computer).
  • Native .reg registry backups via reg export.
  • Full JSON metadata session tracking for 1-click rollback.
• Zero External Production Dependencies:
  • 100% standard Python 3.8+ library (http.server, winreg, ctypes, subprocess).

---

🚀 Quick Start

Option 1: Direct Execution

# Clone repository
git clone https://github.com/chienhaoc/Win11OptDoctor.git
cd win11opt

# Launch (triggers Windows UAC elevation automatically)
python run.py

Option 2: Install as a Python Package

pip install -e .

# Launch CLI entrypoint
win11opt

# Or run as module
python -m backend.win11opt

Advanced CLI Options

# Run backend server on a custom port without auto-opening browser
python run.py --port 9000 --no-browser

# Run headless terminal scan
python run.py --cli-scan

---

🧪 Software Engineering & Testing

Built with software engineering rigor referenced against IEEE 829-2008 documentation standards:

• Automated E2E Playwright Tests (tests/e2e/):
  • test_responsive.py: Multi-resolution responsive validation (1080p, 1440p 200% scaling, mobile viewports).
  • test_ux_consistency.py: Layout shifts (CLS), WCAG 2.1 AA contrast, and UI state consistency.
  • test_logic_validation.py: Data flow math verification (statistics count vs rendered cards) and phase state machine reset behavior.
• Unit Test Suite (tests/unit/):
  • Coverage for hardware detection, service state parsing, registry formatting, profile recommendations, and i18n translation engine.

Run test suite:

pytest tests/

---

🏗️ Project Architecture

win11opt/
├── run.py                 # Primary entrypoint script
├── app.py                 # Backward-compatible entrypoint
├── pyproject.toml         # Packaging configuration
├── setup.py               # Setup installer script
├── LICENSE                # Apache-2.0 License
├── README.md              # English documentation
├── README_zh-TW.md        # Traditional Chinese documentation
├── test_plan.md           # IEEE 829-2008 compliant test plan specification
├── backend/               # Python Backend Package
│   └── win11opt/
│       ├── __init__.py
│       ├── cli.py         # CLI parser & runner
│       ├── config.py      # Diagnostic rules & configuration matrix
│       ├── server.py      # REST API server & static file handler
│       ├── i18n.py        # Internationalization engine
│       └── core/
│           ├── elevation.py   # UAC administrator elevation
│           ├── powershell.py  # UTF-8 decoded PowerShell runner
│           ├── services.py    # Bulk Windows service controller
│           ├── registry.py    # Registry reader & writer
│           ├── ram.py         # Fast C API RAM stats & Top 5 Hogs
│           ├── events.py      # Windows Event Log crash analyzer
│           ├── tasks.py       # Telemetry scheduled tasks
│           ├── hardware.py    # Cached hardware profile detector
│           └── backup.py      # Restore Point & 1-click rollback
├── frontend/              # Glassmorphism Web Interface (HTML5/CSS3/JS)
│   ├── index.html         # Main dashboard markup
│   ├── style.css          # Premium Light Mode design system & CSS variables
│   ├── app.js             # UI state machine & REST API client
│   └── i18n.js            # Frontend dictionary bindings
└── tests/                 # Comprehensive Test Suite
    ├── e2e/               # Playwright E2E test cases
    └── unit/              # Core module unit tests

---

📜 License

Distributed under the Apache License 2.0. See LICENSE for details.