🚜 NREGA Bot

v3.2.13 — Powerful NREGA Automation for Windows, macOS & Linux

⬇️ Download Now · 📘 How to Use · 🐞 Report Bug · 💡 Request Feature

📑 Table of Contents

🎯 Overview
✨ Why NREGA Bot?
🚀 Key Features
📸 Screenshots
🚀 Getting Started
⚙️ How It Works
❓ FAQ
📜 Changelog
🔐 License & Pricing
💬 Support & Community
⚠️ Disclaimer
🧑💻 Developer Guide

🎯 Overview

NREGA Bot is a powerful desktop application that eliminates the manual, repetitive work of the NREGA/MGNREGA portal. It securely drives a browser on your computer to automate data entry, processing and verification tasks — so you can focus on what matters.

🧠 Built for Gram Rozgar Sevaks, Panchayat Secretaries, BDO offices and block-level operators who work with the VB-G-RAM-G / MGNREGA portal every day.

✨ Why NREGA Bot?

	Benefit
⏱️ Huge Time Savings	What takes hours of manual entry finishes in minutes — automate 40+ repetitive tasks
🎯 Zero Typing Errors	The bot reads and fills the portal precisely — no more fat-finger mistakes in job cards, MRs or wagelists
🖥️ True Background Mode	Automations keep running while you work in other tabs — the browser stays minimized
🔄 Retry Failed in 1 Click	Re-process only the failed entries instantly, no need to restart everything
⚡ Smart Instant Updates	SHA-256 verified KB-size core updates — fixes ship in seconds, no re-install
☁️ Cloud Sync & Backup	Your data & settings follow you — switch PCs or restore after a factory reset
📊 Office-Ready Reports	Professional, print-ready Excel/PDF reports — A4 landscape, serial numbers, page numbers
💬 WhatsApp Reports	Results & summary reports delivered straight to your WhatsApp

🚀 Key Features

🏗️ MR & Wage Management

Feature	Description
📋 Demand Automation	Demand laborers from CSV with GP logins & auto 100-day limit adjustment
🗑️ Delete Demand	Remove incorrect demands for single/multiple villages — auto-recovers from portal bugs
✨ Work Allocation	Allocate work & remove allocations across multiple dates
📂 Muster Roll Generator	Auto-generate & download MR PDFs with a handy Merge PDFs button
👥 Mate/Mistri MR	Generate skilled/semi-skilled muster rolls for Mate & Mistri workers
✨ MR Fill	Auto-fill muster rolls with smart holiday handling
⚙️ MSR (MR Payment)	Process & save muster rolls from the MSR Payment page
📤 FTO Generation	FTO verification with Check Pending ABPS Labour workflow
📋 Generate / Send Wagelist	Generate new wagelists & send them for e-FMS payment
🖨️ Duplicate MR Print	Find, save & print all muster rolls + Merge PDFs button
🧱 Material Entry	Dynamic material rows (up to 15), saved material profiles, live GST totals
🏁 Scheme Closing	Close schemes for completed works automatically
✅ Physical Complete	Mark physical completion & auto-forward to Scheme Closing

👷 JE & AE Automation

Feature	Description
✏️ eMB Entry	Auto-fill MB entry pages — professional Excel/PDF export & retry logic
🔍 eMB Verify	Bulk-verify Measurement Book entries in seconds

📝 Records & Workcode

Feature	Description
🏗️ Workcode Generator	Create work codes in bulk by loading categories & reading CSV
🔧 IF Editor	Multi-page IF editing with a flexible UI & simple CSV inputs
🪄 Add Activity	Automate adding activities to work codes
✨ Update Estimated Outcome	Update 'Estimated Outcome' for a list of work codes

🛠️ Utilities & Verification

Feature	Description
⛺ Sarkar Aapke Dwar	Bulk camp entry — applicant/scheme remarks automation
📊 SAD Update Status	Update Sarkar Aapke Dwar application statuses
✨ Zero MR	Submit Zero MR — integrated directly with MR Tracking data
✅ Jobcard Verification	Verify job cards for a village & auto-upload the correct family photo
💳 Verify ABPS	Check worker Aadhaar numbers with NPCI
✨ Resend Rejected Wagelist	Reprocess wagelist payments rejected by the bank
🗑️ Delete Applicant	Bulk-delete jobcard applicants via eKYC Report Excel or CSV
✂️ Workcode Extractor	Parse & extract clean lists of work codes
📎 PDF Merger	Standalone utility to merge multiple PDFs
🌐 Block Data Download	Load your block's Panchayat & Villages from the server (Location Pool) — works even without PO/GP portal login

📊 Reporting

Feature	Description
💸 Pending Bills	Scrape unpaid MRs & Bills into a color-coded professional Excel
📅 NMMS Daily Attendance	Scrape attendance, group photos & worker details into professional Excel
✨ MR Tracking	Real-time MR status (headless) — Pendency Report T0–T8 & Zero MR forwarding
✨ Dashboard Report	Dashboard reports with full export capabilities
✨ Issued MR Details	All e-muster issued works + ABPS Pending Demand block scan
📊 MIS Reports	CAPTCHA solving + multi-sheet MIS Excel downloads
📈 Social Audit Reports	Fetch Social Audit issue details automatically
🆔 eKYC Report	Professional eKYC pending reports

🧠 Smart Tools & General

Feature	Description
🚀 Macro Manager	The automation hub — queue multiple tasks to run sequentially, Bulk Demand via CSV
✨ Login Automation	One-click auto-login to the NREGA portal
💬 WhatsApp Chat	Send files & messages — plus automatic completion notifications
📁 File Manager	Cloud file manager with shareable folder links
🎨 Dynamic UI	Modern interface — Dark/Light theme, skeleton loading & sound effects
☁️ Cloud Sync & Backup	Backup/restore data & settings, or move to a new PC in one click
⚡ Smart Updates	SHA-256 verified core updates — small fixes ship instantly (KB size)
🔁 Retry Failed Button	Re-process only failed entries in any automation with one click

📸 Screenshots

Muster Roll Generator — modern, intuitive dashboard

Duplicate MR Print — find, print & merge muster rolls

MR Tracking — pendency T0–T8 reports & Zero MR forwarding

Dashboard Report — comprehensive views with full export

Demand Automation — bulk labour demand from CSV

eMB Entry — professional export & retry logic

🚀 Getting Started

Prerequisites

Only a supported web browser is needed:

🌐 Google Chrome (recommended)
🔵 Microsoft Edge
🦊 Mozilla Firefox

Installation

Download the installer for your platform:
- Windows: NREGABot-v3.2.2-Setup.exe
- macOS: NREGABot-v3.2.2-macOS.dmg
- Lite (low-end PCs): NREGABot-Lite-v3.2.2-Setup.exe or portable ZIP
Run the installer and launch NREGA Bot.

Quick Start

Register on nregabot.com/trial to get your 30-day free trial key.
Launch the app and activate it with your registered email or the trial key.
From the dashboard, click Chrome / Edge / Firefox — a special controlled browser window opens.
Log in to the VB-G-RAM-G / MGNREGA portal in that window, just as you normally would.
Open the tab for your task, fill in the details (panchayat, work codes, etc.) and hit ▶ Start Automation.
Watch progress in the Logs & Status area — and get results in the Results tab when done, with one-click Export (Excel/PDF/CSV/WhatsApp).

⚙️ How It Works

NREGA Bot is a Python desktop application that securely controls a browser on your machine — it reads the portal's pages, fills forms exactly like a human would, and scrapes results into clean, print-ready reports.

Layer	Technology
🖥️ Desktop GUI	Python · CustomTkinter (modern, themeable UI)
🌐 Browser Automation	Selenium — Chrome / Edge / Firefox
📊 Reports	OpenPyXL (Excel) · FPDF (PDF) · Pillow (PNG images)
💬 WhatsApp	Evolution API — automatic report delivery
☁️ Cloud	License server, cloud sync & auto-update infrastructure
🔄 Smart Updates	Loader + core-zip architecture — SHA-256 verified, KB-size fixes

🔧 For developers: the full architecture guide, entry points and build scripts live in the 🧑💻 Developer Guide section at the bottom. AI agents: AGENTS.md is the compact operating manual to read first.

❓ FAQ

💳 Is there a free trial?

Yes! Register at nregabot.com/trial and you get a 30-day fully-functional free trial. Activate the app with your registered email or the trial key.

🌐 Which browsers are supported?

Google Chrome (recommended), Microsoft Edge and Mozilla Firefox. Pick your browser from the app's dashboard.

🕐 Can I use my PC while an automation runs?

Absolutely. NREGA Bot runs in true background mode — the browser is minimized and the automation continues running while you work in other apps or tabs.

🔄 How do updates work?

Updates use a loader + core-zip architecture. Small fixes ship as KB-size packages that are SHA-256 verified before applying — no re-install needed. The About tab even shows a Download & Install button with the changelog.

📱 Do I get WhatsApp reports?

Yes! When enabled in Settings, each completed automation sends a summary + results Excel to your WhatsApp — plus the web portal can send date-wise combine reports.

💻 I have a low-end PC — will it work?

Yes — a special Lite build is available for low-end PCs with a reduced feature set and no animations/sounds.

📜 Changelog

🆕 What's New in v3.2.9

⚡ eMB Entry Much Faster — a ~25 second stall after every panchayat selection is gone. The postback wait was watching an element fetched after the page had already reloaded, so it could never fire and always burned its full timeout. Most noticeable on Block/PO/JE logins.
🐞 eMB Entry — Multi-Period Crash Fixed — moving to a work's second measurement period threw stale element reference and failed the whole work. Period options are now snapshotted as text, so every period is processed.
⏭️ 'No Muster Roll Available' Is No Longer an Error — a period with no muster roll (eMB already booked, or the MR hasn't reached your login yet) is now reported as Skipped, not a red failure. The summary counts them separately: ✅ entered, ⚠️ skipped, ❌ failed.
🔢 eMB Entry — Correct Work Code in Results — the Work Code column showed a fragment like 22-23); it now shows the real workcode's last 6 digits (e.g. 209915).
🛑 Footer 'STOP ALL' Button Restored — a long status line (eMB Entry's work code + period) filled the whole footer and pushed the STOP ALL button out of view. Status text is now shortened and the right-hand dock always keeps its space.

What's New in v3.2.8

Maintenance release — its job is to make sure every user actually receives the 3.2.5 and 3.2.7 features. If you are already on 3.2.7 there is no new code for you.

🌐 Location Data Pool (Block Sharing) — your Block's Panchayat & Villages sync to the server and are shared with same-block users, so anyone in the block can download them directly (Settings → 🌐 Block Data Download) even without a PO/GP portal login. Only public panchayat/village names are shared — no personal data.
🏘️ Fresh Install — No Need to Add Panchayat — on a new install the onboarding "Add Panchayat" step auto-loads your block's data from the server (green tick) if another user in the same block has already contributed it. Just press Next.
⚡ eMB Entry Faster — panchayat re-selection is skipped when the dropdown already holds the right panchayat, saving ~5-8s of postback per work code. Alert wait cut from 25s to 5s and sleep timers reduced, so long MB entry lists run noticeably quicker.
🐞 eMB Entry 'No Alert' Crash Fix — when the portal showed no alert after Save the whole run used to crash; that entry is now marked 'Failed: No Alert Received' and the rest keep going.

What's New in v3.2.7

⚡ MB Entry Faster — panchayat re-selection skipped when already correct (~5-8s saved per work code); alert wait 25s → 5s; sleep timers reduced.
🐞 MB Entry 'no such alert' Fix — NoAlertPresentException is caught properly; the entry reports 'Failed: No Alert Received' instead of crashing.
🐞 MR Fill Alert Fix — unexpected portal alerts during Save are handled gracefully instead of ending the run.
🐛 Footer Hover Glitch Fixed — hovering Stop All while automation was running made the footer "dance"; hover now changes only the button, never the status label.
🎨 Footer Stop Button Improved — proper pill-button look with border, padding and a light-red → red hover background.

What's New in v3.2.6

📸 Jobcard Verification — Photo Upload Fixed — the Upload Family Photo popup now works reliably: the bot waits for the portal's Ajax ModalPopup instead of a JS alert, and closes the popup window without ever closing the main browser window.
🌐 Jobcard Verification — 'All Villages' in Dropdown — the "process all villages" checkbox is replaced by a proper 🌐 All Villages option in the village dropdown, which reloads when the panchayat changes.

🆕 What's New in v3.2.5

🌐 Location Data Pool (Block Sharing) — your Block's Panchayat & Villages now sync to the server and are shared with same-block users. Anyone in the block can download them directly (Settings → Block Data Download) — even without a PO/GP portal login. Only public panchayat/village names are shared, no personal data.
🏘️ Add Panchayat — Login Not Required — the onboarding "Add Panchayat" step now auto-loads your block's Panchayat & Villages from the server with a green tick — just press Next, even if you have neither PO nor GP login.
🌍 Server-Driven State Registry — new states (Bihar, UP, ...) can now be added from the admin panel without an app update; the app auto-fetches the new configuration every ~2 minutes.
📊 Feature Usage Stats — every automation's usage now syncs to the server, so admins can see which features are used most (per tab, per state) in the Feature Popularity page.
🔄 Factory Reset Simplified — factory reset now needs a single confirmation — one click, no confusing steps.
🔄 Windows Auto-Restart Fixed — the app now restarts reliably on Windows after adding Panchayat/Villages, changing language, or Factory Reset (previously a cmd quoting issue showed 'Windows cannot find').
🔍 Onboarding Login Check — the Add Panchayat step now checks login status in the background: logged-out users see a clear 'login karo' message, GP/PO logins get smart guidance, and expired sessions are detected automatically.
🏘️ GP/GB Login Scrape Improved — panchayat + villages scraping is now more robust for panchayat-level users (saves the panchayat even without a village dropdown, more element IDs tried state-wise).
🐛 Add Activity — Duplicate Fix — if a work code already has the activity, it's now skipped: the bot waits for the activity grid to settle and checks each row's ACT code precisely, so no more double entries.
🔔 Universal WhatsApp Daily Report — the daily 6 AM report setting is now user-level: toggle it on any device and all your devices sync the same state within ~2 minutes. One device being off no longer cancels your morning report.
👥 Multiple Mates per Panchayat (Mate Map) — add several mates for one panchayat in Settings → Mate Map: save them one by one or type comma-separated (both merge, no duplicates), and the list shows all names. eMB Entry now rotates a random mate per measurement, so the same name isn't used everywhere; MR Gen staff mapping gets the same comma + rotation treatment.

🆕 What's New in v3.2.2

🎓 New Onboarding (Welcome Tour) — first launch now runs an interactive 7-step setup wizard: pick your language, launch & log into the browser, add Panchayat & Villages right there, learn the Emergency Stop button, and how to use the app. Replay anytime from the About tab.
🌐 New Language — Hinglish — the whole app now works in Roman Hindi (Hinglish), auto-suggested for Hindi-speaking states. 5 languages total: English, हिन्दी, ಕನ್ನಡ, বাংলা, Hinglish.
🔄 Smart Auto-Restart — the app now restarts itself after adding Panchayat/Villages, changing language, or Factory Reset — new data shows up in every tab immediately (reliable on Windows & macOS).
🎓 Factory Reset + Welcome Tour — factory reset now brings the Welcome Tour back for a fresh setup.
🏘️ Shared Panchayat Scraper — one reliable scraping engine shared by Settings and the onboarding wizard.

What's New in v3.2.1

💥 Crash Reporting — crashes now upload full context (app version, tab/function, error, last 30 log lines) to the server; new admin Crashes tab with filters & CSV export.
📡 Uptime Monitoring — the server self-checks every 5 min (Database, Redis, WhatsApp, WebDAV) and alerts the admin on WhatsApp the moment anything goes down.
🔐 DPDP Compliance — Aadhaar & sensitive PII are masked everywhere; no sensitive data is stored.
🚦 API Rate Limiting — per-key & per-IP rate limits + validation on sync endpoints; live per-key usage stats in the admin panel.
📋 Better Error Logs — admin error logs now carry full context (version, tab, function, time) with export.
⚖️ License & Terms — new in-app License & Terms window (EULA + disclaimer); web privacy/terms/disclaimer pages updated.
🐞 Bug Fixes — admin error summary 500 fix, local-dev fixes, stability improvements.

Previous versions

v3.2.0

📍 Panchayat Column in Results — every results table now shows which row belongs to which Panchayat, even in My Saved Panchayats mode.
🔢 Serial Number (Sr. No.) — a local serial number is now the first column of every results table and export (website serial is ignored).
📅 Smart File Names — exported reports now include date & time in the filename — no more overwrites or manual renaming.
🏘️ Saved Panchayats — process your saved panchayats directly (ABPS Verify, Muster Roll, eMB Verify, Wagelist Gen).
🔁 Multi-Panchayat — enhanced multi-panchayat processing in MR Tracking, MSR and Zero MR.
💬 WhatsApp Report Toggle — a dedicated toggle for WhatsApp report notifications.
🖨️ Print-Ready Excel Reports — A4 landscape, fit-to-width, repeating headers & page numbers — print and submit straight to the office.
🧩 Windows Update Fix — core zip version detection now works correctly.

v3.1.7

🔐 Google Login, 🪪 Passkey (WebAuthn) login, 📧 OTP Login on web
📦 Cloud storage full/nearly-full alert with one-click upgrade/cleanup
▶️ Running automations shown live in the UI footer
🔒 Web portal security & cloud report sync improvements

v3.1.6

🐞 ABPS Verification crash fix (village-wise) + speed boost
💬 WhatsApp throttle protection via global queue (2–6s pacing)
📊 Single WhatsApp setting — summary + Excel in one message
📁 Cloud File Manager — send cloud PDFs to clients via WhatsApp

v3.1.5

🔄 Smart Update Fix — correct version shown after update
🚀 Auto-restart after updates on macOS

v3.1.4

🖥️ Multi-tab workflow — automations run without grabbing browser focus
📑 Auto tab switching — Logs while running, Results when done
🔇 Sound toggle fix

v3.1.3

🌗 One-click theme switch & complete theme coverage
💬 Stacked, colour-coded toast notifications
📡 Online heartbeat, ⚡ reliable 20s update checks, 🔒 SHA-256 verified downloads

v3.1.2

🐞 Fixed 'humanize module missing' crash (About tab & File Manager)
▶️ Running automation indicator in footer

📄 Full changelog: docs/changelog.json

🔐 License & Pricing

Trial: 30-day fully-functional free trial after web registration.
License: A license key is required after the trial to continue using automation features.

Affordable Monthly, Quarterly, Half-Yearly and Yearly plans are available.

Plan	Ideal for
🗓️ Monthly	Trying it out / short projects
🗓️ Quarterly	Regular day-to-day automation
🗓️ Half-Yearly	Serious operators — best value
🗓️ Yearly	Full-time Gram Rozgar Sevaks & offices

👉 Get Your License Key

🎉 Referral Program: Refer a new user with your code (from My Account) and get 15 extra days when they buy their first plan!

💬 Support & Community

📧 Email: nregabot@gmail.com
💬 WhatsApp Community: Join our Group
📘 Instructions: How to Use
🐞 Bug Reports: Contact page

🧑💻 Developer Guide (Architecture)

This section is the technical reference for developers who work on the NREGA Bot source. AI agents: har session start pe AGENTS.md padho — wo compact operating manual hai (quick-start, golden rules, task→file map). Neeche ka section deep dive ke liye hai.

📐 Click to expand — full codebase architecture guide

NREGA Bot is a Python desktop automation tool (CustomTkinter GUI) that automates data-entry tasks on the Indian government's VB-G-RAM-G / MGNREGA portal. It drives a Selenium browser (Chrome/Edge/Firefox) to fill forms, scrape reports, and generate Excel/PDF reports for a user's district → block → panchayat.

⚠️ TWO repos: ye desktop app repo hai. nrega-server/ ek alag independent repo hai (self-hosted NAS git: ssh://rajat@192.168.29.101:/volume1/docker/nrega-server.git, branch master) — submodule nahi, main repo use ignore karta hai (.gitignore). Desktop = GitHub push; Server = NAS push + deploy.sh. Dono alag se ship hote hain.

1. High-Level Architecture

PyInstaller EXE (loader) ──downloads──▶ core_win_vX.zip (source code) ──extracts──▶ runs main_app.py
      │                                                                                    │
      └── splash screen + update check (loader.py / lite_loader.py)                        │
                                                                                           ▼
                                                            NregaBotApp (main_app.py)
                                                            ┌──────────────┬──────────────────┐
                                                            │ Header/footer│ Sidebar nav      │
                                                            │ (UIMixin)    │ (NavMixin)       │
                                                            ├──────────────┼──────────────────┤
                                                            │ License      │ Automation       │
                                                            │ (LicenseMixin)│ (AutomationMixin)│
                                                            └──────────────┴──────────────────┘
                                                                        │
                                                      ~55 lazy-loaded tabs in src/tabs/

Key concept: the "loader + core zip" delivery model

The PyInstaller build only bundles loader.py (or lite_loader.py) plus third-party pip packages. The actual application code (main_app.py, src/) ships as a source zip (core_win_vX.zip / core_mac_vX.zip) built by scripts/build_update.py.
On launch, the loader checks https://nregabot.com/version.json (see config/version.json for the local mirror), downloads the core zip if newer or same-version-but-different-hash (SHA-256 verified), extracts it, and runs main_app.py / lite_app.py from disk.
Implication for pip deps: any third-party package the app code needs (e.g. humanize) MUST be declared as --hidden-import=... in the build scripts — otherwise PyInstaller never sees it because the loader itself doesn't import it. (This caused the "humanize module missing" bug — see build scripts section.)

2. Entry Points

File	Role
`loader.py`	Main app loader. Splash screen, checks/downloads/extracts core zip, then `import main_app; main_app.run_application()`.
`lite_loader.py`	Lite app loader. Compact splash, simpler update path (extracts into `_internal/`), then `lite_app.run_lite_application()`.
`main_app.py`	Full app. Defines `NregaBotApp(ctk.CTk, LicenseMixin, NavMixin, AutomationMixin, UIMixin)` and `run_application()` (single-instance socket on port 60123).
`lite_app.py`	Lite app. `NregaBotLiteApp` — fewer tabs, no sounds/animations/onboarding, emoji icons. Port 60124.
`_smoke_test_tabs.py`	Headless test: instantiates EVERY tab to catch pack/grid TclErrors. Run: `venv/bin/python _smoke_test_tabs.py`.
`scripts/check_imports.py`	Compiles + imports every `.py` file; writes results to `docs/import_check_results.txt`.

3. App State & Mixins

`src/state.py` — `AppState` dataclass

Centralized typed state: license info, active_automations: Set[str], automation_threads, stop_events, tab instances, nav buttons, update info, theme mode, etc. NregaBotApp exposes backward-compatible properties (bottom of main_app.py) that delegate self.app.xxx → self.app_state.xxx, so the 40+ tab files can keep using self.app.<attr> unchanged.

Mixin files (`src/app/`)

File	Mixin	Responsibility
`app_ui.py`	`UIMixin`	Header, footer (status + running-automation indicator), sidebar layout, resize smoothing, theme cycling, sound/minimize toggles, `set_status()`-adjacent widgets.
`app_navigation.py`	`NavMixin`	Sidebar buttons, category filter, lazy tab loading via `show_frame()`, tab caching (`_has_automated` keeps tabs alive after a run), error UI for failed tab loads, workflow delegation to `self.workflows`.
`app_automation.py`	`AutomationMixin`	`start_automation_thread(key, target, args)`, `on_automation_finished()`, emergency stop, `AUTOMATION_DISPLAY_NAMES` map + `_update_running_automation_indicator()`, WhatsApp notification helpers, browser launch delegation, `_quick_login_automation`.
`app_license.py`	`LicenseMixin`	License validation flow, activation window, expiry handling, feature flags (`global_disabled_features`, `trial_restricted_features`).

4. Managers (`src/managers/`)

File	Class	Responsibility
`services.py`	`ServiceManager`	License check/validate (`/api/validate`), update check & install, machine-id via MAC, prevent-sleep (Windows `SetThreadExecutionState` / macOS `caffeinate`).
`browser_manager.py`	`BrowserManager`	Launch Chrome (debug port 9222)/Edge/Firefox, manage Selenium driver, per-thread browser choice.
`workflow_manager.py`	`WorkflowManager`	Macro queue engine: runs a sequence of tab automations (e.g. MR Tracking → eMB Entry), waits for keys in `app.active_automations`, hands off scraped workcodes between tabs.
`icon_manager.py`	`LazyIconManager`	Lazy icon loading with cache (`get("key")`, `get_sized()`, `preload_essential()`).
`sound_manager.py`	`SoundManager`	Plays wav assets from `assets/sounds/`.

5. Tab System (`src/tabs/`)

~55 tabs, each a ctk.CTkFrame. Config lives in src/tab_config.py (get_tabs_definition()) and src/lite_tab_config.py (get_tabs_definition_lite()).
Lazy loading: _lazy_import(class_name, module_path) in tab_config.py imports the module only on first tab open (importlib) and caches the class. This keeps startup fast (no selenium/pandas at boot).
Base class: src/tabs/base_tab.py → BaseAutomationTab(parent, app, automation_key). Provides: log area + status bar, Start/Stop/Retry/Reset buttons, start_automation(), stop_automation(), update_status(), set_common_ui_state(), treeview styling/export (CSV/Excel with openpyxl styling), PNG report generation (generate_report_image), _REPORT_CATEGORY_NAMES (automation_key → report folder name), activity tracking (activity_panchayat/village/details), safe_after() tracked callbacks, _is_alive() guards.
Automation flow: tab's start_automation() → self.app.start_automation_thread( self.automation_key, self.run_automation_logic, args=...) → runs on a daemon thread → on_automation_finished() cleans up, logs, toasts, WhatsApp notify, removes key from active_automations.

Automation keys (automation_key on each tab) demand, work_allocation, muster, mate_mr, mr_fill, msr, gen, send, fto_gen, duplicate_mr, material_entry, mb_entry, emb_verify, wc_gen, if_edit, update_estimate, physical_complete, scheme_closing, add_activity, jc_verify, abps_verify, del_work_alloc, del_demand, delete_applicant, zero_mr, resend_wg, sad_auto, sad_update_status, mr_tracking, dash_report, mis_reports, issued_mr_report, ekyc_report, social_audit_respond, nmms_attendance, pending_bills, macro, pdf_merger, wc_extractor.

Friendly display names for these live in AUTOMATION_DISPLAY_NAMES in src/app/app_automation.py (used by the footer "▶ Running: …" indicator).

6. Footer & Running-Automation Indicator

Built in UIMixin._create_footer() (src/app/app_ui.py) and lite_app.py.

Left side: © copyright, loading spinner, then the running_automation_label showing e.g. ▶ Running: MB Entry, Demand (bold blue). Updated by AutomationMixin._update_running_automation_indicator().
Right side (dock_frame): status_label (Status: Ready), then STOP ALL emergency-stop dot+label, icon buttons (history, cloud files, WhatsApp, settings), server status dot.
_update_running_automation_indicator() is called on start / finish / emergency stop and is safe before the footer exists (winfo_exists() guard).
set_status() (in main_app.py) colors the status label by message keywords (running → blue + spinner, ready → green + success sound, error → red + error sound).

7. Configuration (`src/config.py`)

APP_VERSION (3.2.2), LICENSE_SERVER_URL (env or default), MAIN_WEBSITE_URL, SUPPORT_EMAIL, BETA_BUILD (detected via config/beta.json marker).
COLORS — the central color palette (all UI must use config.COLORS["key"], supports (light, dark) tuples). COLORS_CACHE for fast access.
Per-automation config dicts: MUSTER_ROLL_CONFIG, MSR_CONFIG, WAGELIST_GEN_CONFIG, MB_ENTRY_CONFIG, IF_EDIT_CONFIG, WC_GEN_CONFIG, FTO_GEN_CONFIG, PENDING_BILLS_CONFIG (per-state seed digests), STATE_DEMAND_CONFIG, etc. — URLs + form defaults per portal page.
DEFAULT_LAUNCH_URLS — sites opened when launching managed browsers.
User config (config.json) is read/written via src/utils.py get_config() / save_config() in the app data dir (user_data_dir("NREGABot", "PoddarSolutions")).

8. Utility Layer (`src/utils.py`)

Function	Purpose
`resource_path()`	Path for bundled assets (works in PyInstaller `_MEIPASS` and dev).
`get_data_path()` / `get_user_downloads_path()` / `get_nregabot_path()` / `get_report_path()`	Standard dirs: app data, `~/Downloads`, `~/Downloads/NregaBot/`, `~/Downloads/NregaBot/Report {FY}/…`.
`setup_logging()` / `get_logger()`	Centralized rotating file logger (app data `nregabot.log`) + stderr warnings.
`get_config()` / `save_config()` / `validate_config()`	User config.json helpers (`create_default_config_if_not_exists()` lives in `src/config.py`).
`parse_version()`	Semver compare (replaces `packaging`).
`format_bytes()`	Byte-size formatting — uses `humanize` if installed, built-in fallback otherwise (so the app never crashes if `humanize` is missing from the bundle).
`truncate_workcode()`	Last-6-digits privacy truncation of NREGA workcodes.
`_suppress_overscroll()`	macOS trackpad bounce suppression for scroll frames.

9. Build & Release System

Build scripts

Script	Purpose
`scripts/build_windows.bat`	Main loader (onedir) + Lite loader (onedir) + portable zip + Inno Setup installers. Has `--hidden-import=humanize` + `--hidden-import=src.app.app_automation`.
`scripts/build_macos.sh`	Same for macOS + codesign + DMG.
`scripts/build_beta_portable.bat`	Beta onefile portable build (adds `config/beta.json` marker → `BETA_BUILD=True`).
`scripts/build_update.py`	Builds `dist/core_{mac,win}_v{version}.zip` from a whitelist of top-level entries (never ships `.env`, server code, secrets) and writes SHA-256 into `config/version.json`.
`scripts/installer.iss` / `installer_lite.iss`	Inno Setup scripts.

CI (`.github/workflows/release.yml`)

On push to main: builds Windows (loader + core win zip + Lite portable), Beta portable, Linux loader, then publishes a GitHub release. config/version.json is the source of truth for latest_version, changelog, and core_update hashes (hash_windows/hash_macos).

Update mechanism (SHA-256 hotfix support)

version.json → core_update: version, url(_windows/_macos), force_full_reinstall, hash_windows, hash_macos, generic hash.
Loader (loader.py) / ServiceManager.check_for_updates_background() compare their own platform's hash only; same-version + changed-hash = hotfix re-download. Corrupt download (hash mismatch) keeps the old version.
After build_update.py, copy the printed SHA-256 into config/version.json before release.

10. Data & Assets

Path	Content
`assets/`	`logo.png`, icons (`assets/icons/`), sounds (`assets/sounds/*.wav`), fonts (DejaVu + NotoSansDevanagari for Hindi PDFs), demo CSVs, `material_profiles.json`.
`config/`	`version.json`, `theme.json`, `__init__.py` (beta marker may be bundled here).
`docs/`	`changelog.json` (About → Changelog tab), `license.txt`, guides.
User data dir	`config.json`, `license.dat`, `nregabot.log`, `core_version.json`, `core.zip`, `app_live/` (extracted code).

11. Conventions & Gotchas (IMPORTANT)

Never hard-code colors — use config.COLORS[...]. Supports (light, dark) tuples.
Never call Tk widgets from worker threads — always self.app.after(0, ...).
Never driver.quit() in a tab's destroy() — the automation thread may be using it; cleanup happens in start_automation_thread()'s wrapper finally.
Keep tabs alive after automation — _has_automated flag stops show_frame() from destroying a tab that ran automation (loses logs/results otherwise).
Any new pip package MUST be added as --hidden-import= in BOTH build_windows.bat and build_macos.sh (and release.yml Linux build), because the loader is the PyInstaller entry and app code ships as source. Forgetting this = "ModuleNotFoundError" in release (see the humanize incident). Also add a source-level fallback where feasible.
New tabs: add to src/tab_config.py with a creation_func via _lazy_import, give the tab a unique automation_key, and add the key to AUTOMATION_DISPLAY_NAMES if you want a friendly footer name. Lite tabs go in src/lite_tab_config.py.
Lazy loading is core — don't import selenium/pandas/etc. at module top-level in tabs or the startup time regresses; use function-level imports (selenium already module-level in base_tab.py deliberately).
Report paths go through get_report_path(category, fin_year) → ~/Downloads/NregaBot/Report 2026-2027/<Category>/.
Logging: use get_logger() (never bare print for user-facing logs; print only for debug).
Testing: run venv/bin/python _smoke_test_tabs.py after tab changes and venv/bin/python scripts/check_imports.py before release.

12. Common Task Recipes (where to edit)

Task	File(s)
Change footer / status / running indicator	`src/app/app_ui.py`, `src/app/app_automation.py`, `lite_app.py`
Add/modify a portal automation tab	`src/tabs/<tab>_tab.py` + `src/tab_config.py` (+ `src/config.py` for URLs)
Add a sidebar category or tab	`src/app/app_navigation.py` (`_ICON_KEYS`), `src/tab_config.py`
Fix license/activation	`src/app/app_license.py`, `src/managers/services.py`
Change update flow	`loader.py`, `lite_loader.py`, `src/managers/services.py`, `scripts/build_update.py`, `config/version.json`
Macro queue / multi-tab workflows	`src/managers/workflow_manager.py`
Colors/theme	`src/config.py` (`COLORS`), `config/theme.json`
Release a new version	bump `APP_VERSION` (config.py) + `config/version.json` → run `build_update.py` → copy hash → push (CI builds)

⚠️ Disclaimer

This tool automates interactions with a live government website. The author is not responsible for any changes to the NREGA portal that may cause the application to malfunction.

This software is provided "AS IS" without warranty of any kind. Always double-check automated data for accuracy.

👨‍💻 Author: Rajat Poddar · 🌐 nregabot.com

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.github/workflows		.github/workflows
assets		assets
config		config
docs		docs
mobile_design		mobile_design
nrega-security-audit-output		nrega-security-audit-output
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
NregaBot.code-workspace		NregaBot.code-workspace
README.md		README.md
_smoke_test_tabs.py		_smoke_test_tabs.py
lite_app.py		lite_app.py
lite_loader.py		lite_loader.py
loader.py		loader.py
main_app.py		main_app.py
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
run_server.py		run_server.py
server_loop.py		server_loop.py
skills-lock.json		skills-lock.json
start_server.py		start_server.py

Latest commit

History

Folders and files

Repository files navigation