carmanagement/docs/website-admin-menu-management-plan.md

# Website Admin Menu Management Plan for Company Users

## 1. Goal

Build a website admin system that allows platform administrators to manage menu items shown to company users.

The menu should be controlled centrally by website admins. Companies should automatically receive default menu items based on their subscription plan. Website admins should also be able to add extra menu items for individual companies when needed.

Company admins should not manage menus unless this is introduced later as a separate feature.

---

## 2. Core Concept

The final menu shown to a company user should come from two sources:

```text
Final User Menu = Subscription Default Menu Items + Company-Specific Menu Items
```

Where:

```text
Subscription Default Menu Items:
Managed by website admins and assigned based on subscription plan.

Company-Specific Menu Items:
Managed by website admins and assigned to one company or selected companies.
```

This creates centralized control and avoids letting every company modify the navigation structure independently.

---

## 3. Admin Roles

The system should support website-level admin roles.

Suggested roles:

```text
Super Admin:
- Full access to all menu management features
- Can create, edit, delete, enable, and disable menu items
- Can manage subscription menu templates
- Can assign custom menu items to specific companies

Website Admin:
- Can manage menu items
- Can assign menu items to companies
- Cannot change billing or subscription rules unless allowed

Support Admin:
- Can view company menus
- Can preview menus for troubleshooting
- Cannot create or edit menu items

Company User:
- Can only see the final menu generated for their company and role
```

---

## 4. Subscription-Based Default Menus

Each subscription plan should have a menu template managed by website admins.

Example:

```text
Basic Plan:
- Dashboard
- Profile
- Reports

Pro Plan:
- Dashboard
- Profile
- Reports
- Team Management
- Advanced Analytics

Enterprise Plan:
- Dashboard
- Profile
- Reports
- Team Management
- Advanced Analytics
- Integrations
- Audit Logs
```

When a company is assigned to a subscription plan, the system automatically uses that plan’s menu template.

Website admins should be able to:

```text
- Create subscription menu templates
- Edit default menu items for a subscription
- Reorder default menu items
- Enable or disable menu items
- Mark menu items as required
- Assign menu items to one or more subscription plans
```

---

## 5. Company-Specific Menu Items

Website admins should be able to add menu items for a specific company without changing the global subscription template.

Example:

```text
Company A has Pro Plan:
- Gets all Pro default menu items
- Also gets custom item: Finance Portal

Company B has Pro Plan:
- Gets all Pro default menu items
- Does not get Finance Portal
```

This allows exceptions without changing the subscription plan for every company.

---

## 6. Menu Item Types

The system should support these menu item types:

```text
Internal Page:
Links to a page inside the application.

External Link:
Links to an outside tool or website.

Parent Menu:
A dropdown or folder that contains child items.

Section Label:
A visual grouping label.

Divider:
A visual separator.
```

Each menu item should include:

```text
- Name / label
- Type
- Route or URL
- Icon
- Parent menu item
- Display order
- Status: Active or Inactive
- Open behavior: Same tab or new tab
- Required or optional
- Subscription availability
- Company assignment
- Role visibility
- Created by
- Updated by
- Created date
- Updated date
```

---

## 7. Website Admin Features

The website admin panel should include a **Menu Management** section.

Website admins should be able to:

```text
- View all menu items
- Create new menu items
- Edit existing menu items
- Enable or disable menu items
- Reorder menu items
- Assign menu items to subscription plans
- Assign menu items to individual companies
- Assign menu items to user roles
- Preview a company user’s menu
- View menu history and audit logs
```

---

## 8. Menu Visibility Rules

The system should calculate visibility using this order:

```text
1. Subscription entitlement
2. Company-specific assignment
3. User role
4. User status
5. Menu item status
```

A user should see a menu item only if:

```text
- The item is active
- The user belongs to a company
- The company has access through subscription or direct assignment
- The user’s role is allowed to see it
- The user account is active
```

---

## 9. Important Rule: Menu Visibility Is Not Security

The menu only controls what users see in navigation.

It must not be used as the only access control layer.

Backend APIs and protected pages must still check:

```text
- User authentication
- Company access
- Role permissions
- Subscription access
- Feature entitlement
```

A hidden menu item does not mean the page is secure. Users can still guess URLs, share links, or hit APIs directly.

---

## 10. Subscription Change Behavior

When a company upgrades or downgrades, the menu should update automatically.

### Upgrade Example

```text
Company moves from Basic to Pro:
- Pro default menu items become visible
- Existing company-specific menu items remain unchanged
```

### Downgrade Example

```text
Company moves from Pro to Basic:
- Pro-only default menu items become hidden
- Company-specific items remain only if they do not depend on Pro-only features
```

Do not delete menu history or company-specific assignments during subscription changes.

Instead, mark unavailable items as:

```text
Unavailable due to subscription
```

This allows website admins to understand why an item is not visible.

---

## 11. Database Model

### subscription_plans

```text
id
name
description
status
created_at
updated_at
```

### menu_items

```text
id
label
item_type
route_or_url
icon
parent_id
display_order
open_in_new_tab
is_required
status
created_by
updated_by
created_at
updated_at
```

This table stores all platform-managed menu items.

### subscription_menu_items

```text
id
subscription_plan_id
menu_item_id
display_order
status
created_at
updated_at
```

This table maps menu items to subscription plans.

### company_menu_items

```text
id
company_id
menu_item_id
display_order
status
created_at
updated_at
```

This table maps extra website-admin-assigned menu items to specific companies.

### menu_item_role_visibility

```text
id
menu_item_id
role_id
created_at
updated_at
```

This table controls which roles can see each item.

### company_subscriptions

```text
id
company_id
subscription_plan_id
status
start_date
end_date
created_at
updated_at
```

### menu_audit_logs

```text
id
admin_user_id
action_type
entity_type
entity_id
old_value
new_value
created_at
```

---

## 12. Menu Generation Logic

When a company user logs in, the backend should generate the menu.

Steps:

```text
1. Identify the user.
2. Identify the user’s company.
3. Get the company’s active subscription.
4. Load menu items assigned to that subscription.
5. Load menu items assigned directly to the company.
6. Merge both sets.
7. Remove duplicates.
8. Filter by user role.
9. Remove inactive items.
10. Sort by display order.
11. Return the final menu.
```

Example logic:

```text
subscriptionMenu = getMenuBySubscription(company.subscription_plan_id)
companyMenu = getMenuByCompany(company.id)

finalMenu = merge(subscriptionMenu, companyMenu)
finalMenu = removeDuplicates(finalMenu)
finalMenu = filterByRole(finalMenu, user.role)
finalMenu = filterActiveItems(finalMenu)
finalMenu = sortByDisplayOrder(finalMenu)
```

---

## 13. Duplicate Handling

If the same menu item exists in both the subscription menu and the company-specific menu, the system should show it once.

Recommended priority:

```text
Company-specific assignment overrides subscription assignment for display order only.
```

This means:

```text
- The item appears once
- Website admins can customize order for that company
- The item still keeps the same underlying permissions
```

---

## 14. Admin UI Requirements

The website admin menu management screen should include:

```text
- Menu item list
- Create menu item button
- Edit menu item form
- Status toggle
- Subscription assignment selector
- Company assignment selector
- Role visibility selector
- Drag-and-drop ordering
- Preview by company
- Preview by role
- Audit history
```

---

## 15. Preview Feature

Website admins should be able to preview the menu before saving or while troubleshooting.

Preview options:

```text
- Select company
- Select user role
- View final generated menu
- See why each item is visible or hidden
```

The “why visible/hidden” detail is important.

Example:

```text
Advanced Analytics:
Visible because company has Pro subscription.

Audit Logs:
Hidden because company has Basic subscription.

Finance Portal:
Visible because item is assigned directly to this company.
```

This will save debugging time and reduce support overhead.

---

## 16. Validation Rules

The system should enforce:

```text
- Menu label is required
- Route or URL is required unless item is a parent menu
- External URLs must use HTTPS
- Display order must be valid
- Parent item must exist
- Child item cannot be its own parent
- Required system items cannot be disabled without Super Admin access
- Menu item cannot be assigned to an inactive subscription
- Menu item cannot be assigned to a deleted company
- Duplicate route under the same parent should be prevented
```

---

## 17. Audit Logging

Every website admin action should be logged.

Track:

```text
- Admin user
- Action type
- Affected menu item
- Affected company, if any
- Affected subscription, if any
- Old value
- New value
- Timestamp
```

Important actions to log:

```text
- Created menu item
- Edited menu item
- Disabled menu item
- Enabled menu item
- Assigned item to subscription
- Removed item from subscription
- Assigned item to company
- Removed item from company
- Changed display order
- Changed role visibility
```

---

## 18. Recommended MVP Scope

The first version should include:

```text
- Website admin menu item CRUD
- Assign menu items to subscription plans
- Assign extra menu items to specific companies
- Role-based visibility
- Active/inactive status
- Backend menu generation API
- Audit logging
- Company and role preview
```

Avoid these in the MVP unless absolutely necessary:

```text
- User-specific menu visibility
- Scheduled publishing
- Custom company-managed menu editing
- Approval workflows
- Menu analytics
```

User-specific visibility should be avoided in the first version because it adds significant permission complexity.

---

## 19. API Endpoints

Suggested admin endpoints:

```text
GET /admin/menu-items
POST /admin/menu-items
GET /admin/menu-items/{id}
PUT /admin/menu-items/{id}
PATCH /admin/menu-items/{id}/status
DELETE /admin/menu-items/{id}

POST /admin/menu-items/{id}/subscriptions
DELETE /admin/menu-items/{id}/subscriptions/{subscriptionPlanId}

POST /admin/menu-items/{id}/companies
DELETE /admin/menu-items/{id}/companies/{companyId}

POST /admin/menu-preview
GET /admin/menu-audit-logs
```

Suggested user endpoint:

```text
GET /me/menu
```

The user endpoint should return only the final menu available to the logged-in user.

---

## 20. Success Criteria

The feature is successful if:

```text
- Website admins can manage all menu items centrally.
- Companies receive menu items automatically based on subscription.
- Website admins can add menu items to individual companies.
- Users only see menu items available to their company and role.
- Subscription upgrades and downgrades update menus correctly.
- Hidden menu items do not create security gaps.
- Admin changes are logged.
- Support admins can preview and debug company menus.
```

---

## 21. Key Product Decision

Menu ownership belongs to the platform, not the company.

That means the core system should not include company-admin menu controls. Company-specific customization should be handled by website admins through direct company assignment.

This keeps the model simpler, safer, and easier to support.