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:

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

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

Example menu definition:

{
  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:

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 lang="ar" dir="rtl">

When English or French is selected:

<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.

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:

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:

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

7.2 Subscription-plan entitlement

plan
menuItemId
enabled
displayOrder

7.3 Company override

companyId
menuItemId
enabled
displayOrder
optionalLabelOverride
optionalIconOverride

7.4 Audit record

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:

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:

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:

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

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

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

API

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

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

Shared i18n package

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.