Menu Builder System - Deep Dive Documentation¶

Generated: 2026-02-25 Scope: Full-stack Menu Builder — backend modules, entities, frontend API/services, v2 components, legacy components Files Analyzed: 38+ (8 backend modules, 2 entities, 6 frontend API/services, 9 v2 components, 12 legacy components, + seeds, routes, helpers) Lines of Code: ~8,900+ Workflow Mode: Exhaustive Deep-Dive

Overview¶

The Menu Builder is a full-stack dynamic navigation management system allowing admin users to create, configure, and organize navigation menus (navbar, footer, topbar, bottombar, etc.) with nested, drag-and-drop reorderable items. Each menu item can link to internal content (blogs, pages, categories, tags, packages) or external URLs, with per-item permission controls and icon/color customization.

Purpose: CRUD management of navigation menus and their hierarchical items, with WordPress-style tree editing, drag-and-drop reordering, and multi-location assignment.

Key Responsibilities: - Menu CRUD with soft-delete, restore, permanent delete, bulk operations - MenuItem CRUD with self-referencing parent-child hierarchy (adjacency list) - Drag-and-drop reordering via @dnd-kit - Multi-content-type linking (blogs, pages, categories, tags, packages, custom URLs) - Per-item permission-based visibility control - Menu location assignment (header, footer, sidebar, topbar, bottombar, etc.)

Integration Points: Auth middleware, permission system (checkPermissionAndThrow), blog/page/category/tag entities (polymorphic postType/postId), frontend navigation rendering, Next.js server action revalidation.

Table of Contents¶

1. Database Schema
2. Backend API
3. Frontend API Layer
4. Frontend V2 Components (Active)
5. Frontend Legacy Components
6. Dead Code Inventory
7. User Flows
8. Data Flow
9. Dependency Graph
10. Known Issues
11. Modification Guidance

Database Schema¶

Entity: Menu (table: menus)¶

Relations: - items → @OneToMany(() => MenuItem, item => item.menu) — No cascade defined on ORM side

Entity: MenuItem (table: menu_items)¶

Relations: - menu → @ManyToOne(() => Menu, { onDelete: "CASCADE" }) with @JoinColumn({ name: "menuId" }) - parent → @ManyToOne(() => MenuItem, item => item.children, { nullable: true, onDelete: "CASCADE" }) with @JoinColumn({ name: "parentId" }) - children → @OneToMany(() => MenuItem, item => item.parent)

Hierarchy Model¶

• Pattern: Self-referencing adjacency list on parentId
• Nesting depth: No limit enforced (no depth/level column)
• Ordering: order column (integer, default 0). No unique constraint on (menuId, parentId, order) — duplicate orders possible
• Cascade: onDelete: CASCADE on both menu and parent FKs — but only for hard deletes. Soft-delete does NOT cascade (items become orphans of soft-deleted menus)

Schema Issues¶

Seed Data (Permissions)¶

From saas-boilerplate/src/seed/data/permission.ts, 8 permission entries exist for Menu Builder:

Note: menu.read, menu.restore, menuItem.view, menuItem.read, menu-item.restore are used in service code but NOT seeded — they will always fail checkPermissionAndThrow.

Migration Files¶

None. The project uses TypeORM synchronize: true — no migration files exist anywhere in saas-boilerplate/src/.

Backend API¶

Route Registration¶

From saas-boilerplate/src/app/routes/v1/index.ts: - /menus → menuRoutes (separate Router()) - /menu-items → menuItemRoutes (separate Router())

Both routers apply auth() + contextMiddleware globally. No hasPermission() route-level middleware — all permission checks happen in service layer via checkPermissionAndThrow().

Menu Endpoints (base: /api/v1/menus)¶

MenuItem Endpoints (base: /api/v1/menu-items)¶

Total: 19 endpoints (9 Menu + 10 MenuItem)

Validation Schemas (Zod)¶

Menu: - createMenuValidation: { name: string (required), slug?: string, locations?: string[] } - updateMenuValidation: Identical to create — name is required even for PATCH - deleteMenuByIds: { ids: number[].min(1) } - bulkMenuRestore: { ids: number[].min(0) } — BUG: allows ID 0 and empty array

MenuItem: - createMenuItemValidation: { items: MenuItemSchema[].min(1) } — bulk create - updateMenuItemValidation: All fields optional (proper PATCH) - bulkUpdateMenuItemValidation: { items: BulkUpdateSchema[].min(1) } — requires id, rest optional. Missing permissions field - deleteMenuItemByIds: { ids: number[].positive().min(1) } - bulkMenuItemRestore: { ids: number[].min(0) } — same min(0) bug

MenuItemSchema fields: menuId, title, link, linkType (enum), target, iconClass, color, parentId, order, permissions (string[]), postType (enum), postId, parameters

Service Layer Details¶

menu.service.ts (313 LOC): - Uses getQueryBuilder + BaseQueryBuilder for list queries - Uses checkPermissionAndThrow for auth in every method - Uses generateUniqueSlug for slug creation - Does NOT implement caching (dead cacheKey variable) - ILike prefix match for name uniqueness (buggy — see issues)

menuItem.service.ts (684 LOC — largest file): - Implements caching with getCache/addCache/deleteCacheByPrefix (1-day TTL) - Transactional bulk create/update with queryRunner - validateMenu(), validateParent(), validatePostIfProvided() helpers - mapMenuItemWithChildren() recursive DTO mapper - Hidden getMenuList(type) method for public navigation (NOT exposed via any route)

Frontend API Layer¶

Two Separate API Systems¶

The codebase contains two completely independent API systems that do NOT share query keys or cache:

System A: api/menu-builder/ (Old — used by legacy components)¶

File: api/menu-builder/index.js (676 LOC)

9 of 11 endpoints either don't exist or have payload mismatches.

Composite hook: useMenuBuilder(menuType) combines all hooks + usePages + useLabelGroups.

Issues: 3 console.log debug statements, identity-function memo, no-op labelGroupOptions.

File: api/menu-builder/menu-label.js (68 LOC) - Uses useState/useEffect pattern (not TanStack Query) — inconsistent - BUG: Double-prefixed URL: api.get(\${process.env.NEXT_PUBLIC_API_URL}/menu-labels`)—apialready hasbaseURL- Calls non-existent/menu-labels` endpoint

System B: api/menu/ (V2 — used by current components)¶

File: api/menu/index.js (107 LOC)

BUG: useMenu() passes { limits: 1000 } instead of { params: { limit: 1000 } } — query param never sent.

File: api/menu/menu-item.js (74 LOC)

All v2 endpoints match the backend. Query keys: ["menu"], ["menu", id].

Hook Name Collisions¶

Both systems export identically-named hooks: useCreateMenu, useUpdateMenu, useDeleteMenu. Importing from both in the same file would cause collisions.

Dead Code: Service Files + useMenus Hook¶

Complete dead code chain with zero consumers:

lib/dummyMenuData.js
  → services/menuService.js (USE_DUMMY_DATA = true, all API calls commented out)
  → services/menuItemService.js (USE_DUMMY_DATA = true, all API calls commented out)
  → hooks/useMenus.js (wraps menuService in TanStack Query — zero imports anywhere)

Total dead code: ~334 LOC across 4 files.

Frontend V2 Components (Active)¶

Directory: Sass-boilerplate-frontend-v1/src/components/pages/menu-builder/ Route: /dashboard/settings/menu-builder Total LOC: ~2,500+

Component Tree¶

MenuBuilderPageV2 (422 LOC)
├── MenuSelector (134 LOC)
│   └── CreateMenu dialog (inline)
├── MenuSettingsPanel (156 LOC)
│   └── Location checkboxes (8 options)
├── AddItemsSection (290 LOC)
│   ├── Pages accordion (with search)
│   ├── Blogs accordion (with search)
│   ├── Categories accordion (with search)
│   ├── Tags accordion (with search)
│   └── Custom Link form (title + URL)
├── WordPressStyleMenuTree (510 LOC)
│   ├── SortableMenuItem (DnD wrapper)
│   │   └── MenuItemCard (210 LOC)
│   │       ├── Indent/Outdent buttons
│   │       ├── Edit button → EditItemDialog
│   │       └── Delete button → ConfirmationModal
│   └── DndContext + SortableContext
└── EditItemDialog (240 LOC)
    └── Form: title, link, linkType, target, iconClass, permissions

Supporting utility: lib/menuHelpers.js (125 LOC) — buildMenuTree(), flattenTree(), calculateDepth(), canIndent(), canOutdent()

Component Summaries¶

1. menu-builder-page-v2.jsx (422 LOC) — Main page orchestrator - State: selectedMenuId, localItems (flat array), hasUnsavedChanges, editingItem, isEditDialogOpen - Uses: useMenuById, useBulkCreateMenuItems, useBulkUpdateMenuItems, useDeleteMenuItem, usePages, useBlogs, useBlogCategories, useBlogTags - Key pattern: Batch save model — local state tracks changes, "Save Changes" button triggers bulk create/update - Splits items into newItems (no DB id) and existingItems (have DB id) for separate API calls - handleAddItems: Creates flat items with linkType: "dynamic", auto-assigns order and parentId: null - handleAddCustomLink: Creates item with linkType: "static", target: "_blank"

2. MenuSelector.jsx (134 LOC) - Fetches all menus via useMenu(), renders dropdown + "Create New Menu" button - Inline create dialog: name input → useCreateMenu mutation → auto-selects new menu - Fires onSelect(menuId) callback to parent

3. MenuSettingsPanel.jsx (156 LOC) - Shows: menu name (editable), slug (read-only), 8 location checkboxes (Header, Footer, Sidebar, Topbar, Bottom Bar, Mobile Nav, Mega Menu, Social Links) - Uses useUpdateMenu and usePermanentDeleteMenu - Permanent delete with confirmation modal

4. AddItemsSection.jsx (290 LOC) - 5 content types in accordions: Pages, Blogs, Categories, Tags, Custom Link - Each accordion fetches its own data independently - Items selected via checkboxes, "Add to Menu" button - Debounced search (300ms) per accordion - Custom link form: title + URL inputs

5. WordPressStyleMenuTree.jsx (510 LOC) - Renders flat item list with visual depth indentation (left padding per depth level) - DnD implementation: @dnd-kit/core + @dnd-kit/sortable with verticalListSortingStrategy - handleDragEnd: Moves item in flat array via arrayMove, auto-adjusts parentId based on position - Nesting: Items can be indented (make child of previous sibling) or outdented (move to parent's level) - Uses buildMenuTree only for display calculation, actual state is flat array

6. MenuItemCard.jsx (210 LOC) - Displays: title, link, linkType badge, depth indicator, drag handle - Actions: Edit (opens EditItemDialog), Delete (ConfirmationModal), Indent/Outdent arrows - Wrapped in PermissionWrapper for menu-item.update and menu-item.delete

7. SortableMenuItem.jsx (~60 LOC) - Thin DnD wrapper around MenuItemCard using useSortable hook - Provides attributes, listeners, setNodeRef, transform, transition

8. EditItemDialog.jsx (240 LOC) - Form fields: title, link, linkType (radio: dynamic/static), target (select: _self/_blank/_parent/_top), iconClass, color, permissions (multi-input) - Pre-fills from selected item - Saves via callback to parent (which tracks in localItems)

V2 User Flow¶

1. Select/Create Menu: User picks existing menu from dropdown or creates new one
2. Configure Settings: Set menu name and display locations (checkboxes)
3. Add Items: Browse pages/blogs/categories/tags, check items, click "Add to Menu" — or enter custom link
4. Organize: Drag-and-drop to reorder; use arrow buttons to indent/outdent for nesting
5. Edit Items: Click edit icon to modify title, link, target, icon, permissions
6. Delete Items: Click delete icon, confirm in modal
7. Save: Click "Save Changes" to persist all local modifications to backend in batch

Frontend Legacy Components¶

Directory: Sass-boilerplate-frontend-v1/src/components/pages/menu-builder-old/ Routes: - /dashboard/settings/menu-builder-old → MenuBuilderPage - /dashboard/settings/menu-builder-old/menu-label → MenuLabelPage

Total LOC: 2,821 across 12 files

These routes are still accessible — the old pages are NOT removed, just accessible at -old paths.

Version Evolution (3 Generations)¶

The legacy directory contains 3 visible generations of iterative development:

Architecture Differences: Old vs V2¶

Features in Old Missing from V2¶

1. Label Management Page — Full CRUD with search, pagination, trash/restore
2. Label DnD Reordering — label-manager.jsx
3. Loading overlay during reorder — Blur + spinner
4. Order number badges on cards

Features in V2 Missing from Old¶

1. WordPress-style tree with indent/outdent
2. Batch save with unsaved changes tracking
3. Multi-content-type support (5 types vs 1)
4. Per-item permissions
5. Menu settings panel (name + 8 locations)
6. Content search with debounce
7. Icon class and color per item

Legacy Bugs (Inherited Across Generations)¶

• !depth > 0 logic bug in all 3 menu-item*.jsx — works accidentally for depths 0-1 only
• Edit2 imported but never used in all versions
• Multiple console.log debug statements
• useMemo and Skeleton imported but never used in menu-builder-page.jsx

Dead Code Inventory¶

Total identifiable dead code: ~3,368+ LOC

User Flows¶

V2: Create and Populate a Menu¶

1. User navigates to /dashboard/settings/menu-builder
2. MenuSelector shows "Select a menu" dropdown
3. User clicks "Create New Menu" → dialog opens
4. User types menu name → POST /menus → menu created with auto-slug
5. New menu auto-selected → MenuSettingsPanel and empty tree appear
6. User checks location boxes (e.g., Header, Footer) → PATCH /menus/:id
7. User expands "Pages" accordion in AddItemsSection
8. User searches for "About", checks "About Us" page
9. User clicks "Add to Menu" → item added to local state (unsaved)
10. User drags item to reorder → local state updated
11. User clicks indent arrow → item becomes child of item above
12. User clicks "Save Changes" → POST /menu-items (bulk create for new items)
13. Confirmation toast shown

V2: Edit and Delete Items¶

1. User clicks edit icon on a menu item
2. EditItemDialog opens with pre-filled data
3. User changes title, sets target="_blank", adds permissions
4. User clicks Save → local state updated (unsaved)
5. User clicks "Save Changes" → PATCH /menu-items/bulk-update
6. To delete: user clicks delete icon → ConfirmationModal
7. Confirms → DELETE /menu-items/:id (immediate, not batched)

Data Flow¶

V2 Data Flow¶

[Backend DB] → GET /menus/:id → useMenuById → menuData.items (flat)
                                                    ↓
                                              buildMenuTree() → tree structure (display only)
                                                    ↓
                                              localItems (flat state in page component)
                                                    ↓
                              ┌──────────────┬──────────────┬──────────────┐
                              ↓              ↓              ↓              ↓
                         handleAddItems  handleDrag  handleIndent  handleEdit
                              ↓              ↓              ↓              ↓
                              └──────────────┴──────────────┴──────────────┘
                                                    ↓
                                         hasUnsavedChanges = true
                                                    ↓
                                         "Save Changes" clicked
                                                    ↓
                              ┌──────────────────────────────────┐
                              ↓                                  ↓
                    newItems (no id)                 existingItems (have id)
                              ↓                                  ↓
                  POST /menu-items              PATCH /menu-items/bulk-update
                    { items: [...] }                  { items: [...] }
                              ↓                                  ↓
                              └──────────────────────────────────┘
                                                    ↓
                                    invalidateQueries(["menu", menuId])

Cache Strategy¶

Dependency Graph¶

Backend¶

routes/v1/index.ts
├── MenuBuilder/Menu/menu.routes.ts
│   ├── middlewares/auth.ts
│   ├── middlewares/contextMiddleware.ts
│   ├── menu.validation.ts (Zod schemas)
│   └── menu.controller.ts
│       └── menu.service.ts
│           ├── entity/Menu.ts
│           ├── shared/getDbRepository.ts
│           ├── helper/checkPermissionAndThrow.ts
│           ├── helper/parsePaginationQuery.ts
│           ├── helper/parseBoolean.ts
│           ├── shared/getSortQuery.ts
│           ├── shared/generateUniqueSlug.ts
│           └── builder/getQueryBuilder.ts + QueryBuilder.ts
└── MenuBuilder/MenuItem/menuItem.routes.ts
    ├── middlewares/auth.ts
    ├── middlewares/contextMiddleware.ts
    ├── menuItem.validation.ts (Zod schemas)
    └── menuItem.controller.ts
        └── menuItem.service.ts
            ├── entity/MenuItem.ts
            ├── entity/Menu.ts
            ├── shared/getDbRepository.ts
            ├── helper/checkPermissionAndThrow.ts
            ├── helper/parsePaginationQuery.ts
            ├── helper/parseBoolean.ts
            ├── shared/getSortQuery.ts
            ├── shared/cache.ts (getCache, addCache, deleteCacheByPrefix)
            └── shared/validatePostTypeAndId.ts

Frontend V2¶

app/(dashboard)/settings/menu-builder/page.js
└── components/pages/menu-builder/menu-builder-page-v2.jsx
    ├── api/menu/index.js (useMenu, useMenuById, useCreateMenu, useUpdateMenu, usePermanentDeleteMenu)
    ├── api/menu/menu-item.js (useBulkCreateMenuItems, useBulkUpdateMenuItems, useDeleteMenuItem)
    ├── api/pages (usePages)
    ├── api/blogs (useBlogs, useBlogCategories, useBlogTags)
    ├── lib/menuHelpers.js (buildMenuTree, flattenTree, canIndent, canOutdent)
    ├── MenuSelector.jsx → api/menu/index.js (useMenu, useCreateMenu)
    ├── MenuSettingsPanel.jsx → api/menu/index.js (useUpdateMenu, usePermanentDeleteMenu)
    ├── AddItemsSection.jsx (no API, pure UI)
    ├── WordPressStyleMenuTree.jsx
    │   ├── SortableMenuItem.jsx (@dnd-kit/sortable)
    │   └── MenuItemCard.jsx
    └── EditItemDialog.jsx

Circular Dependencies¶

None detected.

Known Issues¶

Critical (3)¶

High (7)¶

Medium (14)¶

Low (18)¶

Total: 42 issues (3 Critical, 7 High, 14 Medium, 18 Low)

Testing Analysis¶

Test Files¶

None. No test files exist for the Menu Builder system — backend or frontend.

Testing Gaps¶

• No unit tests for menu.service.ts or menuItem.service.ts
• No integration tests for 19 API endpoints
• No component tests for any of the 20+ React components
• No E2E tests for the menu builder user flow
• The circular reference detection (1-level) has no test proving its limitation

Related Code & Reuse Opportunities¶

Similar Patterns in Codebase¶

Reusable Utilities Available¶

Modification Guidance¶

To Add a New Content Type to Menu Items¶

1. Add enum value to MenuItem.postType column in entity/MenuItem.ts
2. Add to Zod enum in menuItem.validation.ts (menuItemSchema.postType)
3. Add validation case in shared/validatePostTypeAndId.ts
4. Add accordion section in AddItemsSection.jsx with corresponding API hook
5. Run TypeORM sync or create migration for the new enum value

To Fix Permission String Inconsistency (#1)¶

1. Decide on ONE format: menu-item.verb (kebab-case, matches seed) or menuItem.verb (camelCase)
2. Update menuItem.service.ts lines using checkPermissionAndThrow to use consistent format
3. Add missing permissions to seed: menu.read, menu.restore, menu-item.restore
4. Remove or update menuItem.view and menuItem.read to menu-item.view and menu-item.read (matching seed)
5. Re-run seed

To Clean Up Dead Code¶

1. Delete services/menuService.js, services/menuItemService.js, hooks/useMenus.js, lib/dummyMenuData.js
2. Delete api/menu-builder/ directory (old system — all endpoints broken)
3. Delete components/pages/menu-builder-old/ directory (12 files, 2,821 LOC)
4. Delete route files: app/(dashboard)/settings/menu-builder-old/ and menu-label/
5. Remove unused imports in entity/GenericPage.ts (MenuItem, OneToMany, ManyToMany)
6. Remove unused service method menuItem.service.ts:getMenuList()
7. Remove Not import from menu.service.ts, IsNull import from menuItem.service.ts

Testing Checklist for Changes¶

• Menu CRUD: create, list, get by id, update, soft-delete, restore, permanent delete
• MenuItem CRUD: bulk create, single update, bulk update, soft-delete, restore, permanent delete
• Permission checks: verify all 12 permission strings work with seeded data
• Hierarchy: create parent, create child, reorder siblings, indent, outdent
• Nesting: verify 3+ levels deep works
• Soft-delete cascade: delete menu, verify items status
• Slug uniqueness: create menus with same name, verify slug differentiation
• Drag-and-drop: reorder items, verify order persisted correctly
• Batch save: add items, reorder, edit, then save all at once
• Location assignment: assign menu to multiple locations, verify rendering
• Content linking: add blog, page, category, tag, custom link items
• Edit dialog: modify title, link, target, icon, permissions

Generated by document-project workflow (deep-dive mode) Base Documentation: docs/index.md Scan Date: 2026-02-25 Analysis Mode: Exhaustive