Desktop application for automated Excel change detection and highlighting
Grooby is a cross-platform desktop application that automatically detects and highlights changes between Excel spreadsheet sheets. Built with Electron for a beautiful native experience and Python for powerful data processing, it provides 100% local data privacy — your files never leave your machine.
- Automatic Change Detection — Compares sheets within Excel files to identify modified rows
- Visual Highlighting — Automatically highlights changed rows in yellow for easy review
- Complete Data Privacy — All processing happens locally; no data is sent to external servers
- Atomic File Operations — Safe file saving prevents data corruption during unexpected shutdowns
- Drag & Drop Interface — Modern glassmorphism UI with intuitive file selection
- Smart Column Filtering — Automatically ignores noisy columns that change too frequently
- One-Click Installation — Bundled as a standalone Windows installer
| Layer | Technology |
|---|---|
| Frontend | Electron 39.2.7, HTML5, CSS3, JavaScript |
| Backend | Python 3.x, FastAPI, Uvicorn |
| Data Processing | Pandas, OpenPyXL |
| Packaging | Electron Builder, PyInstaller |
| Testing | Jest, Pytest, Playwright |
Before you begin, ensure you have the following installed:
- Node.js (v18.x or higher) — Download
- Python (3.8 or higher) — Download
- Git (optional, for cloning) — Download
git clone https://github.com/yourusername/grooby.git
cd groobynpm install# Create a virtual environment (recommended)
python -m venv venv
# Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtnpm startThis launches the Electron app, which automatically starts the Python backend server on 127.0.0.1:8000.
grooby/
├── main.js # Electron main process
├── package.json # Node.js dependencies and scripts
├── electron-builder.json # Electron Builder configuration
├── requirements.txt # Python dependencies
│
├── frontend/ # Electron renderer (UI)
│ ├── index.html # Main UI with glassmorphism design
│ ├── renderer.js # Frontend JavaScript logic
│ └── renderer.test.js # Frontend unit tests
│
├── backend/ # Python FastAPI backend
│ ├── server.py # FastAPI server entry point
│ ├── index.py # Core Excel processing logic
│ ├── file_utils.py # Atomic file operation utilities
│ ├── test_*.py # Backend unit tests
│ └── backend.spec # PyInstaller specification
│
├── e2e/ # End-to-end tests
│ └── *.spec.ts # Playwright test files
│
├── jest.config.js # Jest test configuration
└── playwright.config.js # Playwright test configuration
- File Selection — User drags/drops or browses for an
.xlsxfile - Sheet Detection — Finds sheets matching date pattern (e.g.,
12.23,12.24) - Column Mapping — Identifies common columns between the two most recent sheets
- Noise Filtering — Excludes columns with >50% change rate (configurable)
- Signature Generation — Creates unique signatures for each row
- Change Detection — Compares signatures to find new/modified rows
- Highlighting — Applies yellow highlighting to changed rows (atomic save)
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check for Electron to verify backend is ready |
/process-file |
POST | Process an Excel file and highlight changes |
Grooby includes comprehensive test coverage with unit and end-to-end tests.
# Run frontend unit tests with coverage
npm run test:unit
# Run backend unit tests with coverage
cd backend
pytest --cov=. --cov-report=html
# Run end-to-end tests
npx playwright test| Component | Target Coverage |
|---|---|
| Python Backend | >90% line coverage |
| Frontend (renderer.js) | >95% line coverage |
| E2E Tests | Core user flows |
# Build Python backend to executable
npm run build:python
# Build Electron application (includes Python backend)
npm run build
# Or build everything at once
npm run buildAfter building, you'll find the installer in the dist/ directory:
Grooby Setup x.x.x.exe— Windows NSIS installer
The build process is configured in:
electron-builder.json— Electron packaging settingsbackend/backend.spec— PyInstaller bundling settings
Edit backend/index.py to customize:
# Columns to always ignore during comparison
IGNORED_COLUMNS = ['LOT #']
# Maximum change ratio before a column is considered "noisy"
NOISE_THRESHOLD = 0.5 # 50%Grooby is designed with privacy as a core principle:
- 100% Local Processing — All data stays on your machine
- No Network Calls — The application does not communicate with external servers
- Atomic Saves — File operations use temp files to prevent corruption
- Git-Ignored Data — Excel files are excluded from version control by default
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Write unit tests for new features
- Maintain >90% code coverage
- Follow existing code style
- Update documentation as needed
| Issue | Solution |
|---|---|
| Backend not starting | Ensure Python is in PATH and dependencies are installed |
| "File not found" error | Check that the file path contains no special characters |
| No changes detected | Verify the Excel file has at least 2 date-formatted sheets |
| Build fails | Run npm install and pip install -r requirements.txt again |
- Backend logs appear in the Electron console (View → Toggle Developer Tools)
- Check the terminal for Python process output during development
This project is proprietary software. All rights reserved.
For issues and feature requests, please open an issue on GitHub.