bench get-app https://github.com/KevinBusuttil/isnack

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=KevinBusuttil%2Fisnack)](https://frappegems.com/gems/apps/KevinBusuttil/isnack)

ISNACK - Manufacturing Execution System for ERPNext

Version: 0.0.1
ERPNext Compatibility: v15
License: MIT
Developer: Busuttil Technologies Limited
Contact: kevin@busuttil-technologies.com

---

Table of Contents

1. Overview
2. Core Customizations
   • Manufacturing Execution System (MES)
   • Financial & Accounting
   • Sales & Pricing
   • Reports
3. Data Flow Diagrams
   • Storekeeper Hub Data Flow
   • Operator Hub Data Flow
4. Detailed Operational Flows
   • Storekeeper Hub Operations
   • Operator Hub Operations
5. Custom DocTypes
6. Installation & Configuration
7. License

---

Overview

ISNACK is a comprehensive Manufacturing Execution System (MES) application built as a custom ERPNext v15 app. It provides shop-floor operators and material handlers with specialized interfaces for managing production workflows, material staging, and real-time manufacturing operations.

Key Features

✅ Dual Hub Architecture - Specialized interfaces for storekeepers and operators
✅ Material Staging & FIFO Allocation - Intelligent work order preparation and material allocation
✅ Kiosk-Mode Production Interface - Touch-friendly operator hub for shop-floor use
✅ Barcode Scanning Integration - Real-time material consumption tracking
✅ Label Printing with QZ Tray - Silent printing for finished goods and pallets
✅ Multi-Currency Support - Enhanced financial handling with currency conversion fixes
✅ Custom Invoicing - Service invoice functionality with VAT support
✅ Production Planning Integration - Seamless work order and production plan management

Dual Hub Architecture

ISNACK provides two specialized interfaces optimized for different roles:

• Storekeeper Hub: Material staging and work order preparation interface for warehouse staff
• Operator Hub: Kiosk-mode production interface for shop-floor operators

Both hubs integrate seamlessly with ERPNext's native manufacturing, inventory, and accounting modules while providing role-specific workflows that streamline daily operations.

---

Core Customizations

Manufacturing Execution System (MES)

Storekeeper Hub

Location: isnack/isnack/page/storekeeper_hub/

Purpose: Material staging and work order preparation interface for warehouse staff to efficiently prepare materials for production.

Key Features: - Work Order Buckets: Groups work orders by BOM for consolidated material picking - Consolidated Pick Cart: Single staging list across multiple work orders - FIFO Allocation Engine: Automatically distributes cart quantities using FIFO by WO start time - Stock Entry Creation: Generates material transfer entries for staged materials - Picklist Generation: Optional picklist creation for warehouse picking teams - PO Receipt Workflow: Quick purchase receipt creation from purchase orders - Activity Tracking: Real-time tracking of staged materials, manual entries, and pallet movements

Configuration: - Source warehouse selection for material pulls - Production date (posting date) filtering - Optional pallet ID tagging for tracking - Role-based button visibility via Factory Settings

Operator Hub

Location: isnack/isnack/page/operator_hub/

Purpose: Kiosk-mode production interface designed for shop-floor operators with touch-friendly controls and barcode scanning.

Key Features: - Operator & Line Selection: Multi-line assignment with operator tracking - Work Order Queue: Visual status chips showing WO progress (Not Started, In Process, Completed) - Materials Snapshot: Real-time view of required, transferred, consumed, and remaining materials - Barcode Scanning: Direct material consumption via barcode with duplicate detection - Material Requests: Request additional materials with reason tracking - Material Returns: Per-WO and end-of-shift WIP return workflows - Label Printing: FG carton label printing with QZ Tray integration - Work Order Completion: End WO with SFG consumption and Close Production with packaging

Configuration: - Consume-on-scan behavior (always enabled) - Duplicate scan window (configurable TTL) - Max active operators per job - Material over-consumption threshold alerts

Factory Settings DocType

Location: isnack/isnack/doctype/factory_settings/

Purpose: Centralized MES configuration for all manufacturing and production settings.

Configuration Options:

General: - Batch space handling (reject, convert to underscore/dash, or allow)

Scanning and Consumption: - Consume materials on scan (hardcoded to enabled) - Duplicate scan window (default: 45 seconds) - Max active operators per job (default: 2) - Material over-consumption threshold (default: 150%)

Close Production: - Validation mode (No Validation, All WOs Must Be Ended, Minimum WO Count) - Minimum WO count for validation

Storekeeper Hub: - Roles for stock entry buttons (Mat. Transfer, Mat. Issue, Mat. Receipt)

Item Group Policies: - Packaging item groups - Backflush item groups - Allowed item groups per line

Per Line Rules: - Default semi-finished warehouse - Line-specific warehouse mappings

Label Printing: - Default label template - Default label print format (pallet labels) - Default FG label print format (carton labels) - Default label printer - Default A4 printer - Enable silent printing (QZ Tray) - Allowed pallet UOM types

Per User Defaults: - User-specific printer configurations

---

Financial & Accounting

Journal Entry Override

Location: isnack/overrides/journal_entry.py

Purpose: Implements fix from ERPNext PR #43331 for multi-currency Journal Entry handling.

Issue Fixed: In standard ERPNext v15, GL entries for all rows in multi-currency Journal Entries incorrectly use the same exchange rate from the first row.

Solution: Custom CustomJournalEntry class that uses row-specific exchange rates for each Journal Entry line item. The fix applies automatically to Journal Entries created from Service Invoices.

Key Methods: - _is_from_service_invoice(): Identifies JEs originating from Service Invoices - validate(): Applies exchange rate fix for multi-currency Service Invoice JEs - set_amounts_in_company_currency(): Prevents overwriting of company currency amounts

Payment Reconciliation Override

Location: isnack/overrides/payment_reconciliation.py

Purpose: Extends ERPNext's standard Payment Reconciliation tool with two additional features for USD A/P account reconciliation.

Features Added:

1. Suppress Exchange Gain/Loss — When the Suppress Exchange Gain/Loss checkbox is ticked on the Payment Reconciliation form, all difference_amount values on the allocation rows are zeroed out and difference_account is cleared before reconciliation. This prevents the automatic creation of an Exchange Gain/Loss journal entry, allowing the user to reconcile supplier USD accounts without posting any exchange difference.

2. Reconciliation Date Audit Trail — A custom_reconciliation_date field (type: Date) is automatically populated on every Payment Reconciliation Allocation row when entries are allocated. This provides a complete date audit trail for all reconciliations, not just those with an exchange difference.

Key Methods: - allocate_entries(args): Calls standard ERPNext logic first, then auto-sets custom_reconciliation_date on every row and, if suppress_exchange_gain_loss is checked, zeroes out difference_amount and clears difference_account.

Custom Fields (Fixtures): - Payment Reconciliation.suppress_exchange_gain_loss — Check field, inserted after cost_center - Payment Reconciliation Allocation.custom_reconciliation_date — Date field (read-only), inserted after gain_loss_posting_date, shown in list view

GL Currency Monkey Patch

Location: isnack/monkey_patches/gl_currency.py

Purpose: Fixes currency conversion issues in General Ledger reports.

Implementation: Custom convert_to_presentation_currency() function that uses each entry's posting date for accurate currency conversion instead of a single report date.

Service Invoice DocType

Location: isnack/isnack/doctype/service_invoice/

Purpose: Custom invoice type specifically designed for service-based transactions.

Features: - Multi-currency support with proper exchange rate handling - VAT calculation and tracking - Journal Entry generation with correct currency conversion - Integration with Customer Discount Rules - Flexible payment terms

---

Sales & Pricing

Customer Discount Rules

Location: isnack/isnack/doctype/customer_discount_rules/

Purpose: Manage tiered discount structures for customers.

Features: - Customer-specific discount configurations - Integration with Sales Orders and Service Invoices - Flexible discount calculation rules

Sales Order Customization

Location: isnack/public/js/sales_order_proforma.js

Purpose: Adds proforma invoice functionality to Sales Orders.

Features: - Generate proforma invoices from Sales Orders - Custom print formats for proforma documents - Proforma-specific workflow states

---

Reports

VAT Report

Location: isnack/isnack/report/vat/

Purpose: Detailed VAT analysis and reporting for tax compliance.

VAT Summary Report

Location: isnack/isnack/report/vat_summary/

Purpose: Summarized VAT overview for quick tax period reviews.

Accounts Receivable Proforma Report

Location: isnack/isnack/report/accounts_receivable_proforma/

Purpose: Track proforma invoices and outstanding receivables.

---

Data Flow Diagrams

Storekeeper Hub Data Flow

``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ STOREKEEPER HUB WORKFLOW │ └─────────────────────────────────────────────────────────────────────────────┘

┌──────────────────┐ │ Start Setup │
│ - Select Line │ │ - Source WH │ │ - Posting Date │ │ - Pallet ID │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Work Order │ ← Groups WOs by same BOM │ Buckets │ ← Enables consolidated picking └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Consolidated │ ← Scan/type items │ Pick Cart │ ← Manual row addition │ │ ← Adjust qty/batch/notes └────────┬─────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Allocate & Create Transfers │ │ │ │ ┌────────────────────────────────┐ │ │ │ FIFO Allocation Engine │ │ │ │ - Sort WOs by start time │ │ │ │ - Distribute cart quantities │ │ │ │ - Batch validation │ │ │ └────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────┐ │ │ │ Stock Entry Creation │ │ │ │ - Material Transfer for WO │ │ │ │ - Source → Target warehouse │ │ │ │ - Pallet ID tagging │ │ │ └────────────────────────────────┘ │ └────────┬─────────────────────────────┘ │ ▼ ┌──────────────────┐ ┌──────────────────┐ │ Generate │ │ Quick Actions │ │ Picklist │ │ - Mat. Transfer │ │ (Optional) │ │ - Mat. Issue │ └────────┬─────────┘ │ - Mat.