DEV Community: Mohamed Hamed

Frappe / ERPNext v16.50: The Future of Desktop Icons and Desk Navigation

Mohamed Hamed — Thu, 08 Oct 2026 05:26:47 +0000

What “retiring” really means, what changed in v16.50, and how custom apps should prepare

By Mohamed Hamed (@m7amedenho)

Published: October 2026

Frappe Framework and ERPNext v16.50 introduce a clearer navigation model for the Desk. The official hierarchy is now:

App
└── Module
    └── Sidebar
        ├── DocTypes
        ├── Reports
        ├── Pages
        ├── Workspaces
        └── Dashboards

This change raises an important question for developers and implementers who already use the Desktop Icon grid:

Is Desktop Icon being removed, and should custom apps stop using it immediately?

The short answer is:

The old Desktop Icon grid still works as a compatibility fallback for upgraded sites, but it is retiring. New development should target the Apps screen, Dock, module sidebars, and the new navigation hierarchy.

That distinction matters. “Retiring” does not mean “deleted in v16.50,” and it does not mean that every Desktop Icon-related mechanism suddenly stopped working.

1. What v16.50 actually changed

Frappe describes v16.50 as a polished v16 rather than v17. The release focuses heavily on navigation and user experience while attempting to minimize breaking changes.

The redesigned Desk has a much clearer information hierarchy:

Apps screen
    ↓
Application
    ↓
Dock of modules
    ↓
One sidebar per module
    ↓
DocTypes, reports, pages, workspaces, and dashboards

The Desktop page now focuses on applications. After a user opens an app, its modules appear in the Dock. Opening a module provides the sidebar associated with that module.

This is more than a visual redesign. It changes how navigation should be modeled in a large Frappe application.

The official v16.50 announcement describes the hierarchy as:

App → Module → DocTypes, Reports, Pages, Workspaces, Dashboards, and everything else.

See the official v16.50 announcement.

2. What happens to an existing Desktop Icon grid?

An upgrade does not immediately delete an existing site's Desktop Icons or their arrangement.

According to Frappe's migration documentation:

A site already using the Desktop Icon grid keeps using it after the upgrade.
Its icons and their arrangement are retained.
The grid remains available as a fallback while the site moves to the Apps screen.
New sites start on the Apps screen rather than the old grid.
The grid will be removed in a future release after most sites have migrated.

In other words:

Existing upgraded site
        ↓
Desktop Icon grid remains available
        ↓
Temporary compatibility fallback
        ↓
Migration to Apps screen
        ↓
Future removal of the old grid

The documentation does not currently promise a specific removal version. It would therefore be inaccurate to claim that the grid will definitely disappear in v17, or in any other named release, until Frappe announces that explicitly.

See Migrating a Version 16 site to the new Desk navigation.

3. Desktop Icon, Desktop grid, and Apps screen are not the same thing

Some of the confusion comes from using “Desktop Icon” to describe several related concepts.

The Desktop Icon grid

This is the old home-screen experience containing a grid of icons. It is the part that the official documentation describes as a retiring fallback.

Desktop Icon records

These are records used by the legacy grid and by migration or compatibility behavior. Their continued presence is not, by itself, evidence that the old grid remains the recommended architecture.

The Apps screen

This is the forward-looking Desktop experience. It shows one entry per application and leads the user into that app's modules, Dock, and sidebars.

Therefore, seeing a Desktop Icon DocType or related code in the framework should not be interpreted as a recommendation to base new application navigation on the old grid.

It exists because Frappe must support real installations while they migrate.

4. Why would Frappe maintain something that is retiring?

Deprecation and maintenance can happen at the same time.

ERP installations cannot safely switch navigation models overnight. Existing sites may contain:

custom Desktop Icons;
user-specific icon arrangements;
public and private Workspaces;
custom Workspace Sidebars;
role-dependent shortcuts;
bookmarks and direct links;
multiple custom apps with their own navigation conventions.

Frappe therefore needs to preserve the old experience long enough for administrators and developers to migrate safely. Fixing bugs in that compatibility layer does not contradict its future removal.

It means the project is supporting the transition instead of breaking upgraded sites immediately.

5. Reading the GitHub issues correctly

The GitHub issue history contains reports involving Desktop Icons, Workspaces, layout persistence, permissions, caching, and Workspace Sidebars. These reports need chronological context.

They should not all be presented as evidence that Desktop Icons are currently broken. Some issues were reported during active v16 development and later fixed or released. For example, the Desktop Icon caching issue #36325 was closed and its fix was released in v16.7.0.

At the same time, it would also be inaccurate to claim that every Desktop Icon issue has been resolved. At the time of writing, reports such as creating an icon from the Desktop Icon list #36953 and the broader layout and shortcut report #38292 remain open.

The responsible interpretation is:

The issue history documents an active transition and stabilization process. It contains both completed fixes and unresolved edge cases.

When evaluating an issue, check:

When it was opened.
Which branch and version it affects.
Whether it is open or closed.
Whether a pull request was merged.
Whether the fix has a released version.
Whether the behavior still reproduces on the version you deploy.

This is more useful than treating every historical issue as a current production defect.

6. What should custom app developers use now?

For a new custom app, start with the Apps screen and the new navigation structure.

Declare the application in hooks.py using add_to_apps_screen:

add_to_apps_screen = [
    {
        "name": "my_app",
        "logo": "/assets/my_app/images/logo.svg",
        "title": "My App",
        "route": "/desk/my-module",
        "has_permission": "my_app.utils.check_app_permission",
        "sequence_id": 50,
    }
]

The fields have distinct responsibilities:

Field	Purpose
`name`	The internal app name
`logo`	The icon used on the Apps screen and app Dock
`title`	The label shown to the user
`route`	The destination opened from the app icon
`has_permission`	Optional function controlling access to the app
`sequence_id`	Optional ordering value; lower values appear first

After registering the app, organize its navigation around:

Custom App
├── Module A
│   ├── Module Sidebar
│   ├── Workspaces
│   ├── DocTypes
│   └── Reports
└── Module B
    ├── Module Sidebar
    ├── Pages
    └── Dashboards

The official developer example is available in The desktop and Apps screen.

Do not treat add_to_apps_screen as the entire navigation architecture. It places the application on the Apps screen; the Dock and module sidebars provide the structure inside the application.

7. A practical migration plan for an existing site

The safest strategy is not to delete old icons manually. It is to audit, migrate, test, and then switch.

Step 1: Take a complete backup

Back up the database, public files, private files, site configuration, and the exact revisions of all installed apps. A database backup alone is not a complete rollback plan.

Step 2: Rehearse on staging

Restore production data into an isolated staging environment and run the upgrade there first. Navigation is permission-sensitive, so a successful Administrator test is not enough.

Step 3: Inventory current navigation

Record:

Desktop Icons and their routes;
customized icon arrangements;
public and private Workspaces;
customized Workspace Sidebars;
role-specific links;
custom Pages and Reports;
custom apps that still ship an older sidebar format.

Screenshots are useful here because they make post-migration comparison much faster.

Step 4: Review migration output

Note any modules that were merged, Workspaces placed under Custom Workspaces, and apps still using an older sidebar format.

Step 5: Assign every Workspace to the correct module

In the new structure, a Workspace belongs to a module because that module determines where the Workspace appears. Treat Custom Workspaces as a migration to-do list rather than a permanent information architecture.

Step 6: Curate module sidebars

Review the generated sidebars and rebuild anything that was not carried over. Prefer one clear, curated sidebar per module.

Step 7: Test with real user roles

Test as ordinary users from different departments. Verify:

application visibility;
module visibility;
sidebar contents;
Workspace access;
DocType and Report permissions;
old bookmarks and direct links;
the app icon's landing route;
mobile and smaller-screen behavior.

Step 8: Switch the Desktop page

When staging validation is complete, open Desktop Settings, set Desktop Page to Apps, and save.

This setting affects all users. While the fallback remains available, the site can temporarily return to Desktop Icons without deleting the stored icons or arrangements.

Step 9: Monitor and document

After production rollout, collect feedback from real users, fix missing navigation entries, and document the final module ownership and sidebar structure.

8. Important migration risks

The official migration guide identifies several details worth checking carefully:

Site-level sidebar changes may not be carried over when an app ships a new sidebar for the same module.
Some legacy icons may be hidden if they opened a sidebar that no longer maps cleanly to a Workspace or module sidebar.
Old sidebar records may remain as a read-only archive for recovery purposes.
Existing /desk/... and /app/... links are intended to continue working and may be normalized to the new route structure.
A Workspace without a correct module assignment can be difficult for users to find.

These are strong reasons to test with a copy of production data before switching the whole site.

9. Why this architecture makes sense

A free-form icon grid becomes harder to manage as an ERP grows. Consider a system with:

many installed applications;
dozens of modules;
hundreds of DocTypes;
many Reports and Workspaces;
different access rules by role;
user-specific navigation preferences.

A hierarchy such as:

App → Module → Sidebar → Resource

creates clearer ownership.

It answers practical questions:

Which app owns this functionality?
Which business module does it belong to?
Which sidebar should expose it?
Which users are allowed to see it?
Where should a user land after opening the app?

This structure also makes custom apps easier to reason about and maintain than a growing collection of independent icons.

10. The conclusion for v16.50

The correct interpretation of Frappe / ERPNext v16.50 is not:

Desktop Icons were deleted.

It is:

The old Desktop Icon grid remains temporarily for compatibility.
The new Apps → Modules → Sidebar hierarchy is the target architecture.
Existing sites should migrate deliberately.
New custom apps should build for the new model.

For existing ERPNext installations, there is no reason to panic or delete the legacy configuration immediately. Preserve it, test the conversion, and move users only after the new navigation has been validated.

For developers starting new projects, the direction is already clear: register the application on the Apps screen, define its modules and Dock, and curate one useful sidebar per module.

The practical workflow is:

Back up → Audit → Upgrade on staging → Organize → Test → Switch → Monitor

That approach respects existing users without building new technical debt around a grid that Frappe has officially said will be removed in a future release.

References

Official sources

Selected GitHub issues

#36325 — Caching issue for Desktop Icons — fixed and released in v16.7.0
#36953 — Cannot create a functional Desktop Icon from the list — open at the time of writing
#38292 — Desktop Icon layout, shortcut, and folder issues — open at the time of writing

Issue states can change after publication. Check each issue directly before using its current status in a migration decision.

Author's note

I'm Mohamed Hamed (@m7amedenho), a software developer working with ERPNext and Frappe Framework. I wrote this article to organize what I learned while investigating the navigation changes in v16.50 and to help other developers approaching the same migration.

If you have migrated a customized v16 site to the new navigation, I would be interested to hear which Desktop Icon, Workspace, or Sidebar behaviors required the most attention in your environment.

Stop Writing Boilerplate: Building a Metadata-Driven Node.js Framework from Scratch 🚀

Mohamed Hamed — Tue, 29 Sep 2026 08:22:13 +0000

Let's be honest: setting up a new backend from scratch is tedious.

Even with the rise of AI coding assistants, we often find ourselves generating the same repetitive boilerplate: Models, Controllers, Routes, and Database Migrations for every single entity in our application. As the project scales, this heavily AI-generated code can easily turn into an unmaintainable "spaghetti" mess.

I wanted a better way. I wanted predictability over guesswork. That's why I built DD Framework.

💡 What is DD Framework?

DD Framework is an open-source, metadata-driven framework designed to help developers build robust applications through a low-code approach.

Instead of writing hundreds of lines of imperative code to define a Customer or an Invoice, you simply declare your data structure in a clean JSON file. The framework's core engine takes that JSON and automatically handles the rest.

🛠️ The Tech Stack

Backend Runtime: Node.js (ES Modules)
Server: Fastify (for blazing-fast routing)
Database: PostgreSQL
Query Builder: Knex.js
Frontend (In Progress): Vue.js + Vite

🪄 How It Works (The Magic)

In DD Framework, everything revolves around Entities. Let's say you want to create a Customer module. Instead of writing migration scripts and API controllers, you just create Customer.json:

{
  "name": "Customer",
  "tableName": "tabCustomer",
  "pk_type": "uuid",
  "fields": [
    {
      "fieldname": "full_name",
      "fieldtype": "Data",
      "reqd": 1,
      "unique": 1
    },
    {
      "fieldname": "email",
      "fieldtype": "Data",
      "reqd": 1
    }
  ]
}

Once this file is saved, the DD Framework Engine instantly provides:

Schema Syncing: Hit a single endpoint (POST /api/meta/Customer/sync), and the framework dynamically generates the PostgreSQL table (tabCustomer) with the exact columns and constraints.
Instant REST APIs: You automatically get fully functional CRUD endpoints (POST /api/resource/Customer) without writing a single controller.
Built-in Validation: The engine automatically rejects bad payloads based on your JSON rules (e.g., missing required fields).

No boilerplate. No messy controllers. Just pure, predictable business logic.

🚀 Why This Matters

Zero Boilerplate: Focus entirely on your business requirements, not plumbing.
Standardization: Because the API and DB operations are handled by central "Engines", your entire application behaves consistently.
Future-Proof UI: The frontend (@client_ui, built with Vue.js) fetches this exact metadata to dynamically render forms and data tables on the fly.

🤝 Calling All Open-Source Contributors!

DD Framework is in its early, most exciting stages! The core backend engines (Database, Metadata caching, Schema syncing, and Document CRUD) are functional, but there is so much room to grow.

I am actively looking for developers of all skill levels to join me in building this. Whether you are passionate about Node.js architecture, PostgreSQL optimization, or Vue.js dynamic interfaces, there is a place for you here.

Here is what we are working on next:

🏗️ Schema Engine Upgrades: Adding ALTER TABLE support for existing entities.
🛡️ Advanced Validation: Type-checking and relational data links (Foreign Keys).
🎨 Dynamic Vue.js UI: Building the auto-rendering form engines for the frontend.

Let's build something awesome together!

Check out the repository, drop a ⭐ if you like the concept, and let's start coding:

🔗 GitHub Repository: DD-Framework

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

Mohamed Hamed — Sat, 05 Sep 2026 15:56:04 +0000

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.

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.
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.
Sequential Auto-Retries: Once connectivity is confirmed, queued actions are automatically retried in chronological order.
Sync Queue UI: A dedicated screen allows users to view pending, failed, or completed actions, complete with manual retry and discard controls.
Offline Media: Photos taken offline (e.g., visit proofs) are stored locally, uploaded upon reconnection, and automatically flushed from device storage to save space.
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.