carmanagement/docs/RentalDriveGo_Menu_Subscription_Implementation_Plan.md

# RentalDriveGo Dashboard Menu and Subscription Entitlements Plan

## Document status

- **Purpose:** Implementation plan only
- **Source code changes:** None
- **Target applications:** Dashboard, Admin, API, Database, Shared i18n package
- **Primary objective:** Make the initial dashboard sidebar match the approved seven-item menu while allowing platform administrators to control advanced modules by subscription plan.
- **Localization objective:** Provide one consistent terminology system for English (`en`), French (`fr`), and Arabic (`ar`), including true RTL behavior for Arabic.

---

## 1. Approved baseline sidebar

The default owner sidebar must contain exactly these items, in this order:

| Order | Menu item | System key | Route |
|---:|---|---|---|
| 10 | Dashboard | `dashboard` | `/` |
| 20 | Reservations | `reservations` | `/reservations` |
| 30 | Fleet | `fleet` | `/fleet` |
| 40 | Customers | `customers` | `/customers` |
| 50 | Reports | `reports` | `/reports` |
| 60 | Billing | `billing` | `/billing` |
| 70 | Settings | `settings` | `/settings` |

The existing sidebar styling, layout, branding, theme controls, language controls, responsive behavior, and RTL behavior must remain unchanged.

---

## 2. Advanced subscription modules

The following existing modules will remain available as configurable advanced features:

- Online Reservations
- Offers
- Team
- Contracts
- Notifications
- Reviews
- Complaints

Initial entitlement proposal:

| Module | STARTER | GROWTH | PRO |
|---|:---:|:---:|:---:|
| Dashboard | Yes | Yes | Yes |
| Reservations | Yes | Yes | Yes |
| Fleet | Yes | Yes | Yes |
| Customers | Yes | Yes | Yes |
| Reports | Yes | Yes | Yes |
| Billing | Yes | Yes | Yes |
| Settings | Yes | Yes | Yes |
| Online Reservations | No | Yes | Yes |
| Offers | No | Yes | Yes |
| Team | No | Yes | Yes |
| Contracts | No | Yes | Yes |
| Notifications | No | Yes | Yes |
| Reviews | No | No | Yes |
| Complaints | No | No | Yes |

The platform administrator may later change the advanced-module assignments. Core baseline modules remain protected.

---

## 3. Multilingual terminology and translation contract

All menu items must use immutable system keys and shared translation keys. Application logic must never depend on translated labels.

### 3.1 Approved menu terminology

| System key | Translation key | English (`en`) | French (`fr`) | Arabic (`ar`) |
|---|---|---|---|---|
| `dashboard` | `navigation.dashboard` | Dashboard | Tableau de bord | لوحة التحكم |
| `reservations` | `navigation.reservations` | Reservations | Réservations | الحجوزات |
| `fleet` | `navigation.fleet` | Fleet | Flotte | الأسطول |
| `customers` | `navigation.customers` | Customers | Clients | العملاء |
| `reports` | `navigation.reports` | Reports | Rapports | التقارير |
| `billing` | `navigation.billing` | Billing | Facturation | الفوترة |
| `settings` | `navigation.settings` | Settings | Paramètres | الإعدادات |
| `online-reservations` | `navigation.onlineReservations` | Online Reservations | Réservations en ligne | الحجوزات عبر الإنترنت |
| `offers` | `navigation.offers` | Offers | Offres | العروض |
| `team` | `navigation.team` | Team | Équipe | الفريق |
| `contracts` | `navigation.contracts` | Contracts | Contrats | العقود |
| `notifications` | `navigation.notifications` | Notifications | Notifications | الإشعارات |
| `reviews` | `navigation.reviews` | Reviews | Avis | التقييمات |
| `complaints` | `navigation.complaints` | Complaints | Réclamations | الشكاوى |

These translations are the approved product glossary. Core labels are protected and must not be edited casually from the Admin application.

### 3.2 Shared localization architecture

Recommended structure:

```text
packages/i18n/
├── locales/
│   ├── en.json
│   ├── fr.json
│   └── ar.json
├── glossary.ts
├── validation.ts
└── index.ts
```

Dashboard, Admin, and any future storefront or mobile application must consume the same translation package. Independent translation copies are prohibited because they create terminology drift.

Example menu definition:

```ts
{
  systemKey: "reservations",
  labelKey: "navigation.reservations",
  route: "/reservations"
}
```

The database and API may store `systemKey` and `labelKey`. They must not use translated text as an identifier.

### 3.3 Translation publishing rules

- Core menu translations are locked.
- Custom modules require English, French, and Arabic labels before publishing.
- A label override must provide all three languages.
- Empty translations are rejected.
- Unknown or obsolete translation keys are rejected.
- Translation variables must match across all languages.
- Administrators may configure plan access, roles, order, status, and icons without modifying protected terminology.
- Only `SUPER_ADMIN` may approve changes to the shared product glossary.

### 3.4 Fallback behavior

The application fallback order is:

```text
Requested locale
→ English fallback in local development only
→ Validation or build failure before production deployment
```

Production must not silently display English labels inside French or Arabic interfaces.

### 3.5 Arabic RTL requirements

When Arabic is selected:

```html
<html lang="ar" dir="rtl">
```

When English or French is selected:

```html
<html lang="en" dir="ltr">
<html lang="fr" dir="ltr">
```

Arabic verification must include:

- Sidebar alignment
- Menu indentation
- Chevron direction
- Breadcrumb order
- Form and modal layout
- Text alignment
- Number formatting
- Date formatting
- Currency formatting
- Mobile navigation behavior

Only directional icons should be mirrored. Neutral icons such as Settings, Billing, Fleet, and Reports must keep their original orientation.

### 3.6 Locale-aware formatting

Dates, numbers, percentages, and currencies must use locale-aware formatting rather than translated strings.

```ts
new Intl.DateTimeFormat(locale).format(date);

new Intl.NumberFormat(locale, {
  style: "currency",
  currency: "MAD",
}).format(amount);
```

Stored values remain locale-independent.

---

## 4. Authorization rule

A module is available only when all required conditions are true:

```text
Module is globally enabled
AND module is included in the company's subscription plan
AND the company has not disabled the module
AND the employee role is allowed to use the module
AND the subscription status permits access
```

Company-level settings may disable or reorder entitled modules. They must not unlock a module outside the active subscription plan.

Sidebar visibility alone is not authorization. The API and direct routes must enforce the same entitlement rules.

---

## 5. Role behavior

Subscription access and employee-role access remain separate.

Recommended baseline policy:

| Module | OWNER | MANAGER | AGENT |
|---|:---:|:---:|:---:|
| Dashboard | Yes | Yes | Yes |
| Reservations | Yes | Yes | Yes |
| Fleet | Yes | Yes | Yes |
| Customers | Yes | Yes | Yes |
| Reports | Yes | Yes | Optional |
| Billing | Yes | Optional | No |
| Settings | Yes | Optional | No |

The final role matrix must be approved before implementation. The screenshot represents the owner-level default menu, not automatic access for every employee.

---

## 6. Subscription-status behavior

| Subscription status | Menu behavior |
|---|---|
| `ACTIVE` | Full entitled menu |
| `TRIALING` | Full entitled menu |
| `PAST_DUE` | Configurable restricted or read-only behavior |
| `SUSPENDED` | Recovery menu only |
| `EXPIRED` | Recovery menu only |
| `CANCELLED` | Recovery menu only |
| Missing subscription | Onboarding or recovery menu only |

Recommended recovery menu:

- Dashboard
- Billing
- Settings

This keeps account recovery possible without exposing paid operational modules.

---

## 7. Data model

### 7.1 Menu module catalog

Each module should define:

```text
id
systemKey
defaultLabel
localizedLabels
routeOrUrl
icon
defaultOrder
parentId
minimumRole or allowedRoles
isRequired
isGloballyEnabled
createdAt
updatedAt
```

### 7.2 Subscription-plan entitlement

```text
plan
menuItemId
enabled
displayOrder
```

### 7.3 Company override

```text
companyId
menuItemId
enabled
displayOrder
optionalLabelOverride
optionalIconOverride
```

### 7.4 Audit record

```text
actorId
action
targetType
targetId
before
after
reason
createdAt
```

---

## 8. Implementation phases

## Phase 1: Confirm the menu contract

### Work

- Approve the seven baseline items.
- Approve the initial advanced-module plan matrix.
- Approve the employee-role matrix.
- Define protected system fields.
- Define subscription-status behavior.
- Confirm whether companies may customize labels and icons.
- Approve the English, French, and Arabic terminology glossary.
- Confirm which translation fields are protected.

### Deliverable

A frozen entitlement matrix and protected-module contract.

### Exit criteria

- No unresolved module ownership questions.
- No unresolved role-access questions.
- No unresolved downgrade behavior.
- No unresolved translation or RTL terminology decisions.

---

## Phase 2: Database migration and seed

### Work

- Create or update the menu catalog.
- Seed the seven baseline modules.
- Assign the baseline modules explicitly to `STARTER`, `GROWTH`, and `PRO`.
- Seed the advanced-module plan assignments.
- Normalize menu order.
- Create company-override records only where required.
- Add unique constraints for `systemKey`.
- Add audit support if missing.
- Detect and report existing assignments that exceed subscription access.
- Make the migration idempotent.

### Deliverable

Database migration, seed, and rollback procedure.

### Exit criteria

- Re-running the migration causes no duplicates.
- No navigable module relies on implicit plan access.
- Existing companies receive deterministic menus.

---

## Phase 3: Central entitlement resolver in the API

### Work

Create one canonical entitlement service used by both menu generation and API authorization.

Suggested responsibility:

```ts
resolveModuleAccess({
  companyId,
  employeeId,
  systemKey,
})
```

The resolver must evaluate:

- Global module state
- Active subscription plan
- Subscription status
- Explicit plan entitlement
- Company override
- Employee role
- Required recovery access

### Deliverable

A reusable entitlement service with unit tests.

### Exit criteria

- Menu generation and API guards use the same decision logic.
- Company overrides cannot grant higher-plan access.
- Missing plan assignments mean unavailable.

---

## Phase 4: Harden menu-management API

### Work

- Protect required modules.
- Prevent ordinary administrators from changing:
  - `systemKey`
  - Core routes
  - Required status
  - Core plan assignments
  - Core role assignments
  - Parent relationships
- Validate unique system keys.
- Prevent circular parent relationships.
- Require explicit plan selection for new navigable modules.
- Record all changes in the audit log.
- Require a reason and expiration for exceptional plan overrides.
- Add clear validation errors.

### Deliverable

Secure admin menu endpoints and boundary tests.

### Exit criteria

- Required modules cannot be weakened through general update endpoints.
- Invalid menu trees are rejected.
- All entitlement-changing actions are auditable.

---

## Phase 5: Enforce advanced-module API access

### Work

Apply reusable entitlement middleware to advanced modules:

```ts
requireModuleEntitlement("online-reservations")
requireModuleEntitlement("offers")
requireModuleEntitlement("team")
requireModuleEntitlement("contracts")
requireModuleEntitlement("notifications")
requireModuleEntitlement("reviews")
requireModuleEntitlement("complaints")
```

Also enforce baseline role restrictions where applicable.

### Deliverable

Server-side module protection across all relevant routes.

### Exit criteria

- Entering a hidden route manually does not bypass access.
- Calling an advanced API directly does not bypass the subscription.
- Unauthorized responses are consistent and testable.

---

## Phase 6: Refine the Admin menu-management interface

### Work

Create a clear plan matrix as the primary management view:

```text
Module | STARTER | GROWTH | PRO | Roles | Enabled | Order
```

Add:

- Plan tabs or columns
- Required-item locks
- Role controls
- Ordering controls
- Company and role preview
- Subscription-status preview
- Audit history
- Warning before removing a module used by active companies
- Supported icon selector instead of unrestricted icon text
- Advanced configuration restricted to `SUPER_ADMIN`

### Deliverable

A safer, plan-oriented administration interface.

### Exit criteria

- An administrator can configure advanced subscriptions without editing routes or system keys.
- The preview matches the actual dashboard menu.
- Protected items are visibly locked.

---

## Phase 7: Update the Dashboard sidebar

### Work

- Replace the large hardcoded fallback with the seven approved baseline items.
- Preserve the exact approved order.
- Keep the API-generated menu as the source of truth.
- Distinguish:
  - Loading state
  - API failure
  - Successful empty response
  - Successful populated response
- Treat a successful empty response as intentional.
- Never restore advanced modules after an empty response.
- Use a role-aware safe fallback only when the API genuinely fails.
- Remove the separate Subscription item from the initial menu.
- Keep subscription access available through Billing or Settings.
- Preserve visual design and unrelated behavior.

### Deliverable

A deterministic sidebar matching the approved design.

### Exit criteria

- A `STARTER` owner sees exactly seven items.
- No menu flicker exposes restricted modules.
- RTL, mobile, theme, and localization behavior remain intact.

---

## Phase 8: Route guards in Dashboard and Admin

### Work

- Align frontend route guards with API entitlements.
- Show a clear access-denied or upgrade-required screen.
- Do not silently redirect users to unrelated pages.
- Prevent stale cached menus after plan or role changes.
- Invalidate menu data after admin updates.

### Deliverable

Consistent frontend route protection.

### Exit criteria

- Hidden modules cannot be opened by entering their URL.
- Downgrades remove route access without requiring a new login.
- Upgrade messaging is explicit and accurate.

---

## Phase 9: Implement shared localization validation

### Work

- Create or update the shared `packages/i18n` package.
- Add the approved `en`, `fr`, and `ar` navigation keys.
- Replace hardcoded menu labels in Dashboard and Admin with translation keys.
- Validate that all locale files contain the same required keys.
- Validate that interpolation variables match across languages.
- Reject empty, unknown, and obsolete keys.
- Add CI checks for translation completeness.
- Add development logging for missing keys.
- Ensure Arabic applies `lang="ar"` and `dir="rtl"` at the document root.
- Verify locale-aware dates, numbers, and MAD currency formatting.
- Prevent translated labels from being used in permissions, routes, plan assignments, or database lookups.

### Deliverable

Shared translation package, approved glossary, validation script, and CI enforcement.

### Exit criteria

- Every required English key exists in French and Arabic.
- No navigation label is hardcoded in Dashboard or Admin.
- Core glossary terms are protected.
- Arabic uses true RTL layout.
- Missing translations fail CI before deployment.

---

## Phase 10: Testing

### API tests

- Explicit plan assignment is required.
- Company override cannot upgrade a plan.
- Required items cannot be disabled by ordinary admins.
- Suspended subscriptions receive only recovery access.
- Role restrictions remain active.
- Advanced APIs reject unauthorized requests.
- Audit entries are created.

### Localization tests

- Every navigation key exists in English, French, and Arabic.
- Core terminology matches the approved glossary exactly.
- Missing or empty translations fail CI.
- Interpolation variables match across locales.
- Switching language does not change routes, permissions, subscription access, or system keys.
- French labels do not overflow.
- Arabic labels do not truncate.
- Arabic sets `lang="ar"` and `dir="rtl"`.
- Directional icons mirror correctly and neutral icons do not.
- Dates, numbers, and MAD currency values format correctly by locale.

### Dashboard tests

- `STARTER` owner sees exactly seven items.
- Approved order is preserved.
- Empty successful response remains empty.
- API failure uses only the safe fallback.
- Advanced modules appear only when entitled.
- Direct routes are blocked.
- Mobile and desktop menus behave consistently.
- EN, FR, and AR labels render correctly.
- Arabic remains true RTL.

### Admin tests

- Plan toggles save correctly.
- Locked modules cannot be modified.
- Preview matches the generated employee menu.
- Invalid parent relationships are rejected.
- Removing a widely used entitlement produces a warning.
- Audit history displays the change.

### Deliverable

Unit, integration, boundary, and end-to-end test coverage.

---

## Phase 11: Deployment and rollback

### Deployment order

1. Database migration and seed
2. API entitlement resolver
3. API route enforcement
4. Admin management interface
5. Dashboard sidebar and route guards
6. End-to-end verification

### Rollback requirements

- Database rollback or compensating migration
- Feature flag for new entitlement enforcement
- Ability to restore previous menu assignments
- Audit record of rollback actions
- No destructive deletion of historical menu configuration

### Exit criteria

- Production smoke tests pass.
- Existing companies retain expected access.
- No restricted module is exposed.
- Recovery access remains available.

---

## 9. File-level work areas

Expected targets, subject to repository verification:

### Dashboard

```text
src/components/layout/Sidebar.tsx
src/components/layout/DashboardAccessGuard.tsx
src/components/layout/Sidebar.boundary.test.ts
src/components/layout/DashboardAccessGuard.boundary.test.ts
```

### Admin

```text
src/app/dashboard/menu-management/page.tsx
related menu-management components
related API client modules
related tests
```

### API

```text
src/modules/menu/menu.service.ts
src/modules/menu/menu.entitlement.ts
src/middleware/requireModuleEntitlement.ts
menu administration routes
advanced-module routes
related unit, boundary, and E2E tests
```

### Database

```text
Prisma schema
menu seed
subscription entitlement seed
migration
rollback or repair script
```

### Shared i18n package

```text
packages/i18n/locales/en.json
packages/i18n/locales/fr.json
packages/i18n/locales/ar.json
packages/i18n/glossary.ts
packages/i18n/validation.ts
packages/i18n/index.ts
related localization tests
```

No file should be changed until the repository structure is verified against these expected paths.

---

## 10. Non-goals

This milestone will not:

- Redesign the sidebar visually.
- Change dashboard branding.
- Change the theme system.
- Change localization architecture.
- Replace existing pages.
- Introduce machine translation at runtime.
- Allow translated labels to control routes, permissions, or entitlements.
- Add unrelated subscription billing features.
- Grant tenant administrators permission to alter platform routes.
- Treat hidden navigation as sufficient security.

---

## 11. Definition of done

The implementation is complete only when:

- The initial owner sidebar contains exactly the seven approved items.
- The order matches the approved design.
- Advanced items are explicitly assigned by subscription plan.
- Company overrides cannot bypass subscription entitlements.
- Employee roles remain enforced.
- Subscription status affects access.
- Direct frontend routes are protected.
- Direct API calls are protected.
- Required system items cannot be weakened by ordinary administrators.
- Admin previews match actual dashboard results.
- All changes are audited.
- Existing visual behavior remains unchanged.
- English, French, and Arabic use the approved shared terminology.
- Arabic uses true RTL behavior.
- Missing or inconsistent translations fail CI.
- Routes, permissions, subscriptions, and API logic use immutable system keys rather than translated labels.
- Tests pass across Dashboard, Admin, API, and Database.
- Deployment and rollback procedures are documented.

---

## 12. Execution gate

Implementation must not begin until these items are approved:

1. Baseline seven-item menu
2. Advanced-module plan matrix
3. Employee-role matrix
4. Subscription-status policy
5. Company customization limits
6. Required-item protection rules
7. Database migration strategy
8. Approved EN/FR/AR glossary
9. Translation fallback and CI policy
10. Arabic RTL acceptance criteria

This prevents the usual ritual of coding first and discovering the business rules afterward.