Decoupling Menu and Page Architecture in Moqui: A Stable & Scalable Navigation Framework

Technical Discussion
1

In large applications, menus serve as the system entry point, while pages implement specific features.
However, Moqui’s current default behavior tightly binds the two — menus are dynamically generated from Screen XML subscreens.
This creates several issues:

  • :cross_mark: Any Screen XML parsing error in any component can break the entire menu
  • :cross_mark: Menu maintenance becomes tightly dependent on component structure
  • :cross_mark: Permissions, ordering, icons, and i18n are scattered and inconsistent
  • :cross_mark: Hard to extend and hard to manage in large systems

:bullseye: Core Idea: Fully Decouple Menus from Pages

By introducing a metadata-driven Menu Registry, we achieve:

  • :white_check_mark: Menus become an independent data source
  • :white_check_mark: Pages are just pages — their structure no longer affects menus
  • :white_check_mark: No more “menu disappears due to an XML error”
  • :white_check_mark: Unified permissions, ordering, icons, and internationalization
  • :white_check_mark: Each component can define its own menu without subscreens

:puzzle_piece: The New Three-Layer Architecture

UI Layer (Vue/Quasar)
       ↓
Menu Service Layer (MenuData API)
       ↓
Menu Registry (XML configuration)

Menu Registry – controls what the menu looks like
Menu Service – provides stable JSON to the frontend
Screen Pages – keep only functional logic, fully independent from menus

:shield: Key Benefits

1) 100% Error Isolation

Screen XML broken? Component not found? Permission error?
:right_arrow: Menus still load normally.
No more global navigation failures.

2) Maintenance Becomes Simple

Menus are centrally managed — no need to modify subscreens or page structure.

3) Significant Scalability

  • Centralized multilingual support
  • Centralized icons, descriptions, ordering
  • Any component can register its own menu with a simple XML block

4) Fully Backward-Compatible

Works with all existing Screens without any modifications.

:wrench: Implementation Highlights (Simplified)

  • Add: menu-registry-schema.xml
  • Add: Menu service get MenuData
  • Update: qapps.xml menuData logic to load menu registry first
  • Add: Multi-level fallback logic ensuring the navigation never fails

:test_tube: Verification Completed

  • :check_mark: Menu stability under page XML errors
  • :check_mark: Component-level menu testing
  • :check_mark: Performance testing (avg <200ms)
  • :check_mark: Stress & concurrency testing
  • :check_mark: Menu system health-check API

:pushpin: Conclusion

This architecture resolves Moqui’s long-standing menu–page coupling issue and delivers:

“Menu = stable system entry point (independent)”
“Page = functional implementation (isolated)”

Feedback, suggestions, and collaboration from the community are welcome.
If you need sample files or implementation references, I can provide them.