Project Structure

Project Structure

ByteRescue/
├── app.py                      # launcher: `python app.py`
├── byterescue/
│   ├── app.py                  # GUI only (Tkinter) -- ByteRescue main window + RecoveryCenter
│   ├── applog.py                # log file setup + Tk/thread exception hooks (logs/byterescue.log)
│   └── recovery/                # the actual recovery engine, importable/testable without Tkinter
│       ├── signatures.py       # SIGNATURES metadata + carve/validate logic
│       ├── text_recovery.py    # text-pattern detection (ASCII/UTF-8/UTF-16)
│       ├── filesystem.py       # FAT12/16/32 boot sector, directory, and deleted-entry parsing
│       ├── scanner.py          # ChunkedReader, RecoveryScan (pause/resume/cancel/progress/log)
│       └── hex_reference.py    # educational HEX_CODE_REFERENCE (never used by the scanner)
├── logs/                        # created at runtime, git-ignored -- byterescue.log
├── tests/
│   ├── fixtures.py             # synthetic test files (and FAT16/FAT32 images), built in memory
│   ├── test_signatures.py
│   ├── test_text_recovery.py
│   ├── test_scanner.py
│   ├── test_filesystem.py
│   └── test_gui_recovery_center.py
├── requirements.txt
├── ByteRescue.bat               # thin double-click shim -> ByteRescue.ps1
├── ByteRescue.ps1               # real launcher: elevate, ensure Python, launch
├── .github/
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SUPPORT.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
└── LICENSE

Design principle: GUI vs. engine

The recovery engine is deliberately separated from the GUI:

• byterescue/recovery/ — the carving/validation/scanning logic, importable and unit-testable without Tkinter or a display
• byterescue/app.py — the Tkinter GUI only, wiring user actions to the recovery engine

This split is why the test suite (see Testing) can cover carving correctness, chunk-boundary handling, cancellation, and filesystem parsing without needing a display — only test_gui_recovery_center.py needs real Tkinter widgets.

Module reference

File	Responsibility
byterescue/app.py	Main window, drive listing, file/folder analysis, Hex Viewer, Recovery Center window
byterescue/applog.py	Log file setup, Tk.report_callback_exception hook, sys.excepthook/threading.excepthook hooks
byterescue/recovery/signatures.py	The SIGNATURES table (magic bytes, end-offset strategy) and carve/validate logic — see Recovery Signatures
byterescue/recovery/text_recovery.py	ASCII/UTF-8/UTF-16 LE/BE plausible-text-run detection with confidence scoring
byterescue/recovery/filesystem.py	FAT12/16/32 boot sector/BPB parsing, recursive directory walking, deleted-entry recovery — see Supported File Systems
byterescue/recovery/scanner.py	ChunkedReader (overlap-buffered chunked reads) and RecoveryScan (pause/resume/cancel/progress/log)
byterescue/recovery/hex_reference.py	Educational hex/byte reference table for the Hex Viewer's lookup panel

See also Testing for how each module is covered, and Contributing for how to propose changes to any of them.