DEV Community

Cover image for Building a Fully Offline-First Flutter App for ERPNext: The RedLine Architecture and Sync Engine
Mohamed Hamed
Mohamed Hamed

Posted on

Building a Fully Offline-First Flutter App for ERPNext: The RedLine Architecture and Sync Engine

#erpnext #flutter #offlinefirst #dart

Introduction: The Field Sales Connectivity Problem

One of the most persistent challenges in enterprise software development is bridging the gap between a centralized backend system and field employees operating in areas with poor or zero internet connectivity.

For field sales representatives, an inability to connect to the company's ERP means lost sales, delayed data entry, and frustrated customers. To solve this, Red Tech For Technology developed RedLine—an open-source, fully offline-first mobile application built with Flutter, deeply integrated with the ERPNext / Frappe ecosystem.

This article breaks down the architecture, technical stack, and core features of RedLine, serving as a comprehensive guide on how to build robust offline-capable apps for ERPNext.

What is RedLine?

RedLine is a mobile extension of an ERPNext deployment tailored specifically for field sales teams in the MENA region. Featuring a native Arabic (RTL) interface, it empowers sales representatives to create documents, collect payments, log GPS-tagged visits, and track approvals directly from their smartphones, without needing a continuous server round-trip.




Technical Stack & Architecture

Building a true offline-first application requires a solid foundation for local storage and intelligent network handling.

  • Framework: Flutter (stable channel, Dart SDK ^3.12.2)
  • Backend: ERPNext / Frappe (REST and RPC APIs)
  • Local Storage (Database): Drift (SQLite) for managing the offline queue and reference-data caching.
  • Networking: Dio (with automatic session-refresh handling).
  • Connectivity: connectivity_plus backed by a custom real server reachability check, preventing false-positive network signals.
  • Core Libraries: flutter_secure_storage, geolocator, printing/pdf, local_auth.

The Offline-First Sync Engine: How It Works

The crown jewel of RedLine is its offline synchronization engine. Unlike basic caching, RedLine implements a Full Offline Queueing System.

  1. Action Queueing: When a user creates a Sales Order, Customer Visit, Material Request, Customer Registration, or Expense Claim without an internet connection, the action is serialized and stored in the local Drift SQLite database.
  2. Reachability Verification: The app does not blindly trust the device's network interface. It actively pings the server to ensure a live, stable connection before attempting synchronization.
  3. Sequential Auto-Retries: Once connectivity is confirmed, queued actions are automatically retried in chronological order.
  4. Sync Queue UI: A dedicated screen allows users to view pending, failed, or completed actions, complete with manual retry and discard controls.
  5. Offline Media: Photos taken offline (e.g., visit proofs) are stored locally, uploaded upon reconnection, and automatically flushed from device storage to save space.
  6. Read-Through Caching: Reference data like Customer Statements and Due Invoices are cached locally with a clear "last updated" timestamp.

Note on Financial Integrity: Operations requiring absolute concurrent accuracy—like invoice creation, payment collection, and immediate stock transfers—are intentionally locked as online-only to prevent conflicting updates (e.g., bypassing a shared credit limit).

Comprehensive Feature Breakdown

1. Sales and Order Management

  • Sales Orders: Create, edit, and track orders with automatic, strict credit-limit validation against the customer's outstanding balance.
  • Sales Invoices: Supports immediate stock deduction, return processing, and payment-schedule management.
  • On-Device PDF Generation: Instantly generate and share PDFs for orders and invoices locally, requiring zero server processing.
  • GPS Validation: Geographic coordinates are captured and attached to transactions as verifiable proof of origin.

2. Payments & Treasury

  • Payment Entries: Collect payments against outstanding invoices while properly managing payment-term due dates and treasury allocations (cash/bank/mode of payment).
  • Role-Based Discounting: Document-level and per-item discounts are gated; only region managers can edit them based on configurable limits, keeping them hidden from standard reps.
  • Treasury Views: Detailed treasury statements track cash and bank movements seamlessly.

3. Customer CRM & Field Operations

  • Customer Management: GPS-tagged registration, credit limit display, price lists, and payment term configurations. Filtered heavily by territory mapping.
  • Account Statements: Full GL-based customer statements with expandable transaction details and PDF exports.
  • Visit Logging: Log visits, collections, or reactivations with GPS enforcement and an interactive calendar view. Tracks overdue customers based on configurable territory rules.
  • Two-Leg Warehouse Transfers: Reps can initiate Material Requests, warehouse keepers prepare shipments, and reps confirm receipt directly from the app.
  • Expense Claims: Integrated vehicle logging (fuel/maintenance) and personal expenses with auto-resolution of approvers and payable accounts.

4. Workflows & Approvals

  • ERPNext Workflow Support: Full compatibility with Frappe's native multi-level approval chains (Region Manager ➔ Accounts ➔ General Manager) utilizing role-based transitions.
  • Notification Center: A unified, generic pending-approvals screen for bulk actions, paired with an in-app notification center (backed by Frappe’s Notification Log).

5. Advanced Dashboards

  • Rep Dashboard: Quick actions and recent-activity feeds.
  • Team Dashboard (Managers): Region managers access independently sortable metrics per rep (sales, collections, outstanding debt, visit counts) ensuring a granular view of team performance.

6. Enterprise-Grade Security

  • Domain-based login against ERPNext instances.
  • Secure token management via flutter_secure_storage.
  • Biometric unlock (fingerprint/FaceID) integration for rapid, secure field access.

Open Source & Contribution

We strongly believe in contributing back to the ERPNext and Flutter communities. RedLine is open-source and released under the GPL-3.0 License.

Currently, the UI is Arabic (RTL) focused. We invite the community to explore the architecture, test the offline engine, and help us implement English (LTR) localization (i18n).

🔗 **Check out the repository on GitHub: https://github.com/m7amedenho/Redline-Representative-App-ERPNEXT

If you are an ERPNext implementer or a Flutter developer, we would love your feedback, bug reports, and pull requests!

Let’s build the ultimate offline mobile tool for the Frappe ecosystem, together.

Top comments (0)