redesign the homepage

2026-06-26 16:27:21 -04:00
parent 256ff0814e
commit d7fb7b7a7b
1030 changed files with 107374 additions and 2657 deletions
@@ -0,0 +1,47 @@
+# RentalDriveGo Phase 16 Design Migration
+
+## Outcome
+
+The Phase 16 visual system has been applied at source level to the legacy application front ends in this archive:
+
+- `homepage`: retained as the authoritative Phase 16 marketing implementation already present in the legacy archive.
+- `admin`: migrated to the Phase 16 token palette and component treatment; navigation was rebuilt as a responsive, accessible application shell.
+- `dashboard`: migrated to the same semantic surfaces, typography, borders, shadows, focus treatment, dark theme, and blue/orange action hierarchy.
+- `storefront`: migrated to the same public-site surfaces, conversion treatment, cards, forms, dark theme, and brand naming.
+- `api`: intentionally unchanged. A visual migration should not casually rewrite business logic because that is how weekends disappear.
+
+## Design rules applied
+
+- Blue is the operational primary color.
+- Orange is reserved for conversion emphasis and focus visibility.
+- Green is restored to success/status meaning instead of being used as a disguised primary action.
+- Light and dark themes share semantic tokens rather than unrelated hard-coded palettes.
+- English and French remain LTR; Arabic continues to use document RTL and an Arabic font fallback stack.
+- Interactive controls use a minimum 44px target, visible focus treatment, reduced-motion handling, and high-contrast fallbacks.
+- Cards and panels use the Phase 16 radius, border, surface, and shadow hierarchy.
+- The retired `RentalDriveGo` name was replaced with `RentalDriveGo` throughout all frontend source files.
+
+## Important source finding
+
+The supplied `RentalDriveGo_Phase16_Evidence_Package_v1.0.zip` is an evidence and launch-governance package, not the Phase 16 source repository. It contains 98 files, while its manifest describes a separate 648-file repository that was not included. The legacy archive already contained most of that repository's marketing homepage implementation: 182 files match the Phase 16 manifest checksums exactly. That embedded homepage implementation was therefore used as the reliable visual source of truth rather than fabricating a new design from launch paperwork.
+
+## Files added
+
+- `admin/src/styles/phase16-tokens.css`
+- `dashboard/src/styles/phase16-tokens.css`
+- `storefront/src/styles/phase16-tokens.css`
+- `scripts/validate-phase16-design.mjs`
+- `DESIGN_MIGRATION_REPORT.md`
+- `PHASE16_DESIGN_MIGRATION_MANIFEST.json`
+
+## Validation performed
+
+- Parsed 633 TypeScript and TSX source files with TypeScript 5.8 syntax validation: passed.
+- Checked 53 CSS files for balanced rule blocks: passed.
+- Verified all three migrated apps import the Phase 16 tokens: passed.
+- Verified no retired `RentalDriveGo` branding remains in frontend source: passed.
+- Ran `node scripts/validate-phase16-design.mjs`: passed.
+
+## Validation not claimed
+
+A full dependency-backed build and browser regression suite was not run. The supplied legacy archive omits its root workspace configuration and the local packages referenced as `@rentaldrivego/types` and `@rentaldrivego/database`. The Phase 16 evidence upload also omits the source repository and dependency lockfile it references. Those are packaging defects in the inputs, not facts to conceal with optimistic prose.
@@ -0,0 +1,33 @@
+# RentalDriveGo Public Chrome Refactor Report
+
+## Completed
+
+1. Extracted the dashboard public navbar into `components/public/PublicNavbar.tsx`.
+2. Extracted the dashboard public footer into `components/public/PublicFooter.tsx`.
+3. Added `PublicPageLayout` as the reusable composition layer for authentication and onboarding pages.
+4. Updated sign-in, create-account, forgot-password, reset-password, verify-email, onboarding, and invitation pages to use the public component API.
+5. Preserved legacy component paths through compatibility exports.
+6. Moved storefront navbar/footer assembly out of the Next.js route layout and into reusable public components.
+7. Added active-page semantics to dashboard sign-in and create-account navbar actions.
+8. Added focused tests and implementation documentation.
+
+## Deliberately unchanged
+
+- Authentication requests and API endpoints
+- Redirect behavior between storefront, dashboard, and admin applications
+- Language and theme persistence
+- Embedded workspace behavior
+- Authenticated dashboard and admin navigation
+
+## Validation performed
+
+- Parsed all TypeScript and TSX source files successfully.
+- Verified all relative and `@/` local imports resolve.
+- Verified every `use client` directive remains the first statement.
+- Verified sign-in and create-account import and render `PublicPageLayout`.
+- Verified the storefront route layout no longer assembles navbar/footer inline.
+- Verified embedded password-recovery navigation preserves `embedded=1`.
+
+## Validation limitation
+
+A complete Next.js build was not executed because this archive does not include the monorepo root, workspace packages, lockfile, or installed dependencies referenced by the application package files. Static source validation was completed instead; pretending that equals a production build would be charmingly irresponsible.
@@ -0,0 +1,232 @@
+{
+  "schema_version": "1.0",
+  "project": "RentalDriveGo",
+  "migration": "Apply Phase 16 design system to legacy Archive.zip frontends",
+  "generated_at": "2026-06-26T02:14:35+00:00",
+  "source_archives": {
+    "legacy_archive": "Archive.zip",
+    "phase16_evidence": "RentalDriveGo_Phase16_Evidence_Package_v1.0.zip"
+  },
+  "scope": {
+    "homepage": "retained as embedded Phase 16 source of truth",
+    "admin": "migrated",
+    "dashboard": "migrated",
+    "storefront": "migrated",
+    "api": "unchanged"
+  },
+  "validation": {
+    "typescript_syntax_files": 633,
+    "typescript_syntax": "passed",
+    "css_files_checked": 53,
+    "css_balance": "passed",
+    "design_migration_validator": "passed",
+    "full_build": "not run because root workspace and local packages are absent from supplied archive"
+  },
+  "changed_file_count": 34,
+  "files": [
+    {
+      "path": "DESIGN_MIGRATION_REPORT.md",
+      "status": "added",
+      "bytes": 3260,
+      "sha256": "35c41d70484b917b38991791dfb2feb3e78234e4f30e2c99ba922d3d90ab83a6"
+    },
+    {
+      "path": "scripts/validate-phase16-design.mjs",
+      "status": "added",
+      "bytes": 1891,
+      "sha256": "7a35fad2750bccc09c24f24c1d57594048b040f24d4cde7639fa1a2ce3d63e64"
+    },
+    {
+      "path": "storefront/src/app/layout.tsx",
+      "status": "modified",
+      "bytes": 1833,
+      "sha256": "6fed4ef50a886e1c551b6456b46c5fc785b02a4be988aef06fa95c28443bbd27"
+    },
+    {
+      "path": "storefront/src/app/globals.css",
+      "status": "modified",
+      "bytes": 7525,
+      "sha256": "49e03206558248eb5de2b9a8463be6e0b43e01df518bc0b625fe2953a18185c6"
+    },
+    {
+      "path": "storefront/src/components/MarketplaceFooter.tsx",
+      "status": "modified",
+      "bytes": 4632,
+      "sha256": "169d04dcf0976d2637ef5371ca295e9c362bd089d8d6ec313b4e8b4131d5bdd3"
+    },
+    {
+      "path": "storefront/src/components/MarketplaceHeader.tsx",
+      "status": "modified",
+      "bytes": 10438,
+      "sha256": "25afc57ff9893f255eddf19580e84b510e6032764daaa5727e2e8d669dca4213"
+    },
+    {
+      "path": "storefront/src/styles/phase16-tokens.css",
+      "status": "added",
+      "bytes": 4214,
+      "sha256": "0e7fb35fb2833ff564c1188e39735349a8df901938fa87f2dc1b931dd4f04cd0"
+    },
+    {
+      "path": "storefront/src/app/(public)/explore/[slug]/vehicles/[id]/page.tsx",
+      "status": "modified",
+      "bytes": 13979,
+      "sha256": "9edf8da13e50cabcb2a126b300c71cb0b7a096a31d11d364e37dc09eeb625d3b"
+    },
+    {
+      "path": "dashboard/src/app/layout.tsx",
+      "status": "modified",
+      "bytes": 2133,
+      "sha256": "09399551351e3c7015e6700c3892cf81f2b45cf4d1b835e01645580e73608c05"
+    },
+    {
+      "path": "dashboard/src/app/globals.css",
+      "status": "modified",
+      "bytes": 16161,
+      "sha256": "0d01004900a4a6c078e98167c910d02b5fa29b4ebeafe0520a45cb7f9274c8b8"
+    },
+    {
+      "path": "dashboard/src/styles/phase16-tokens.css",
+      "status": "added",
+      "bytes": 4214,
+      "sha256": "0e7fb35fb2833ff564c1188e39735349a8df901938fa87f2dc1b931dd4f04cd0"
+    },
+    {
+      "path": "dashboard/src/components/layout/PublicFooter.tsx",
+      "status": "modified",
+      "bytes": 8348,
+      "sha256": "657f96cc725459f7bf7a668fe616aee4d295625c15366204b5987176fd60c8b8"
+    },
+    {
+      "path": "dashboard/src/components/layout/PublicHeader.tsx",
+      "status": "modified",
+      "bytes": 10250,
+      "sha256": "3e5ace09e73afbb95f09a1acf164011764cc789474430962426793564b8db459"
+    },
+    {
+      "path": "dashboard/src/components/layout/Sidebar.tsx",
+      "status": "modified",
+      "bytes": 18500,
+      "sha256": "d0f7571149a073c39b6a1b4331e6055d8347a8092bd858d7128a37a19847b4d7"
+    },
+    {
+      "path": "dashboard/src/app/forgot-password/ForgotPasswordPageClient.tsx",
+      "status": "modified",
+      "bytes": 6888,
+      "sha256": "9b6bbc1479529c51d5dd65ce0dffa4ed6245a1de687c2cc9b2f62d3a396a8f83"
+    },
+    {
+      "path": "dashboard/src/app/onboarding/page.tsx",
+      "status": "modified",
+      "bytes": 10593,
+      "sha256": "a2255be38766258da3495191ce793da21992b6f4c13520d760959b7eff5ccc8e"
+    },
+    {
+      "path": "dashboard/src/app/reset-password/ResetPasswordPageClient.tsx",
+      "status": "modified",
+      "bytes": 11998,
+      "sha256": "3a8f0c268c825097da5a8814c26c2526103536b7b3e6f3f5d04e0311cd3fbe27"
+    },
+    {
+      "path": "dashboard/src/app/verify-email/page.tsx",
+      "status": "modified",
+      "bytes": 5176,
+      "sha256": "e1fc11c7e2af90c4b3614a1a8c6b9babe2ea5e9884eaa4e94fc0994462d554d6"
+    },
+    {
+      "path": "dashboard/src/app/sign-up/[[...sign-up]]/SignUpForm.tsx",
+      "status": "modified",
+      "bytes": 14464,
+      "sha256": "976e8f9244a8ca64e092373831970e3c4d7197ead33e3c478f6e8d9d375f9c3e"
+    },
+    {
+      "path": "dashboard/src/app/sign-in/[[...sign-in]]/SignInPageClient.tsx",
+      "status": "modified",
+      "bytes": 19760,
+      "sha256": "861d033b4b86792644538f69a38634d46d6c58d43e87bbeb67dcef806cf6ab24"
+    },
+    {
+      "path": "dashboard/src/app/(dashboard)/settings/page.tsx",
+      "status": "modified",
+      "bytes": 42414,
+      "sha256": "c46bdfd9c1c14d471b1aa03cca5e6d91f49dd8405aa27502f040bd97c0d5a64d"
+    },
+    {
+      "path": "admin/src/app/layout.tsx",
+      "status": "modified",
+      "bytes": 1210,
+      "sha256": "aaa6c6aedb14972a159a9bcf9f8dc0bdedd2681d8a1c37be989644975c94c243"
+    },
+    {
+      "path": "admin/src/app/globals.css",
+      "status": "modified",
+      "bytes": 8317,
+      "sha256": "4134ea739c645e1550e75d16fdf1b45c13392fd153250840c1272603adbd2832"
+    },
+    {
+      "path": "admin/src/styles/phase16-tokens.css",
+      "status": "added",
+      "bytes": 4214,
+      "sha256": "0e7fb35fb2833ff564c1188e39735349a8df901938fa87f2dc1b931dd4f04cd0"
+    },
+    {
+      "path": "admin/src/app/dashboard/layout.tsx",
+      "status": "modified",
+      "bytes": 10294,
+      "sha256": "8390dba373ae0f8d02e8d872f5b0f1736f60553bf33e90f8c07c02207dedadda"
+    },
+    {
+      "path": "admin/src/app/dashboard/page.tsx",
+      "status": "modified",
+      "bytes": 13442,
+      "sha256": "87995a735f7665723c791a6d528a14ebd78e529105e1bfa14654221248b62ca5"
+    },
+    {
+      "path": "admin/src/app/dashboard/admin-users/page.tsx",
+      "status": "modified",
+      "bytes": 12067,
+      "sha256": "64dfa83abc16aef56347c1d832edb2b30f5f11497a6cb2908c5158d891031983"
+    },
+    {
+      "path": "admin/src/app/dashboard/audit-logs/page.tsx",
+      "status": "modified",
+      "bytes": 4369,
+      "sha256": "0db9f45a4486dd4c3a8c89e82618fe49bf3f555aff9a7e8e16b028d2b53d72ef"
+    },
+    {
+      "path": "admin/src/app/dashboard/billing/page.tsx",
+      "status": "modified",
+      "bytes": 48678,
+      "sha256": "598125e6be30d184c2277269e163bd3f54605a839a63041fa57ba27cb03cdadd"
+    },
+    {
+      "path": "admin/src/app/dashboard/companies/page.tsx",
+      "status": "modified",
+      "bytes": 8622,
+      "sha256": "3513aa5a4ac525c0a6887cb3d77299c595b921e3e7f93001095f81f73f19fe31"
+    },
+    {
+      "path": "admin/src/app/dashboard/containers/page.tsx",
+      "status": "modified",
+      "bytes": 18580,
+      "sha256": "d01c7cddedf9fb222554f8ea48fa44a515baae353b6675496eea7578b1c0a105"
+    },
+    {
+      "path": "admin/src/app/dashboard/renters/page.tsx",
+      "status": "modified",
+      "bytes": 6988,
+      "sha256": "5ae947e70d674b930a5fc39f1c0577c25bb7c2ca484c761129fe091019aa0034"
+    },
+    {
+      "path": "admin/src/app/dashboard/site-config/page.tsx",
+      "status": "modified",
+      "bytes": 41636,
+      "sha256": "800108cec0ea22c84ea8f60452ddb633e472237505a16a8bcc73ad89467b08ea"
+    },
+    {
+      "path": "admin/src/app/dashboard/companies/[id]/page.tsx",
+      "status": "modified",
+      "bytes": 50874,
+      "sha256": "5b763c4280f9d561004dbb08faa945b7b868f48086ca3b0ac62cacb228db02d1"
+    }
+  ]
+}
@@ -0,0 +1,43 @@
+{
+  "package": "RentalDriveGo_Phase16_Operational_UI_v1.0",
+  "generatedOn": "2026-06-25",
+  "scope": [
+    "dashboard",
+    "admin"
+  ],
+  "includedApplications": [
+    "homepage",
+    "storefront",
+    "dashboard",
+    "admin",
+    "api"
+  ],
+  "designAuthority": "Phase 16 homepage implementation",
+  "routeCoverage": {
+    "admin": 12,
+    "dashboard": 19
+  },
+  "validation": {
+    "typescriptSourceFilesParsed": 596,
+    "typescriptSyntaxFailures": 0,
+    "localImportsChecked": 190,
+    "unresolvedLocalImports": 0,
+    "designGate": "passed",
+    "productionBuild": "not run: missing monorepo root, workspace package, lockfile, and installed dependencies"
+  },
+  "keyFiles": [
+    "admin/src/styles/phase16-tokens.css",
+    "admin/src/app/globals.css",
+    "admin/src/app/dashboard/layout.tsx",
+    "dashboard/src/styles/phase16-tokens.css",
+    "dashboard/src/app/globals.css",
+    "dashboard/src/app/(dashboard)/layout.tsx",
+    "dashboard/src/components/layout/Sidebar.tsx",
+    "dashboard/src/components/layout/TopBar.tsx",
+    "scripts/validate-phase16-design.mjs"
+  ],
+  "documentation": [
+    "PHASE16_OPERATIONAL_UI_REPORT.md",
+    "docs/PHASE16_OPERATIONAL_UI_GUIDE.md"
+  ]
+}
@@ -0,0 +1,95 @@
+# RentalDriveGo Phase 16 Operational UI Migration Report
+
+**Date:** 2026-06-25  
+**Scope:** Operator dashboard and platform admin  
+**Design authority:** Existing Phase 16 homepage implementation and its blue/orange semantic design system
+
+## Result
+
+The dashboard and admin applications now use the same visual language as the Phase 16 homepage rather than behaving like separate products. The migration changes shared shells, global tokens, navigation, page hierarchy, cards, forms, tables, status treatments, responsive behavior, dark mode, RTL behavior, and focus states. API business logic and route contracts were deliberately left unchanged.
+
+## Repository recovery
+
+The previous navbar/footer refactor archive omitted the `homepage` and `api` applications. This package was rebuilt from the complete Phase 16 archive, then overlaid with the public navbar/footer refactor before the operational UI migration. The final repository contains:
+
+- `homepage`
+- `storefront`
+- `dashboard`
+- `admin`
+- `api`
+- validation scripts and documentation
+
+## Shared visual system
+
+Both operational applications now consume matching `phase16-tokens.css` files with:
+
+- Homepage blue as the operational action color
+- Orange reserved for conversion, focus, warning, and selected emphasis
+- Shared light and dark surface mappings
+- Shared 10 px, 16 px, 24 px, and 32 px radius scale
+- Shared 44 px minimum interactive target
+- Shared 76 px topbar and 272 px desktop sidebar dimensions
+- Shared card, overlay, and focus shadows
+- Inter for Latin content and Noto Sans Arabic fallbacks for Arabic
+
+## Dashboard changes
+
+- Rebuilt the authenticated shell with the Phase 16 page background, sidebar, sticky topbar, content width, and responsive spacing.
+- Reworked sidebar branding, active navigation, user card, status marker, RTL logical borders, and mobile behavior.
+- Reworked the topbar search, page title, status pill, notifications, account controls, and semantic icon buttons.
+- Migrated all 19 dashboard routes to the shared page-heading or hero pattern.
+- Applied shared styling to overview metrics, quick actions, reservations, contracts, online reservations, fleet, customers, team, reviews, complaints, offers, billing, subscription, reports, notifications, and settings.
+- Preserved printable contract styling as a document surface while aligning its surrounding application controls.
+
+## Admin changes
+
+- Rebuilt the admin shell with the same Phase 16 sidebar, topbar, page background, status treatment, mobile drawer, language controls, theme controls, and user card.
+- Migrated all 12 admin routes to the shared page-heading or hero pattern.
+- Standardized companies, company details, renters, administrators, billing, pricing, containers, audit logs, notifications, menu management, site configuration, and overview pages.
+- Converted operational create/save/preview actions from orange to homepage blue. Orange remains available for promotions, conversion previews, warnings, and focus.
+- Standardized dynamic form controls through the shared `.field` utility.
+
+## Shared component and CSS contract
+
+The main reusable classes are:
+
+- `.rdg-app-shell`
+- `.rdg-workspace`
+- `.rdg-sidebar`
+- `.rdg-nav-item`
+- `.rdg-topbar`
+- `.rdg-app-main`
+- `.rdg-app-content`
+- `.rdg-page-hero`
+- `.rdg-page-heading`
+- `.rdg-page-kicker`
+- `.panel`
+- `.card`
+- `.field`
+- `.btn-primary`
+- `.btn-secondary`
+- `.btn-conversion`
+
+## Behavior preserved
+
+- Existing routes and URL structure
+- Authentication and access guards
+- API calls and data mutations
+- English, French, and Arabic support
+- True RTL layout behavior through logical properties
+- Light, dark, and system theme behavior
+- Embedded authentication behavior through `embedded=1`
+- Print behavior for contracts
+
+## Validation completed
+
+- 596 TypeScript/TSX source files parsed with zero syntax failures.
+- 190 local and alias imports checked in admin/dashboard with zero unresolved paths.
+- 31 operational route pages checked for a Phase 16 page heading or hero.
+- CSS brace balance checked for the migrated stylesheets.
+- Shared shell, token, responsive, forced-color, auth-layout, and retired-brand assertions passed.
+- Final archive integrity is checked after packaging.
+
+## Build limitation
+
+A production Next.js build was not run because the supplied archive does not include the monorepo root, root lockfile, root workspace configuration, installed dependencies, or the referenced `@rentaldrivego/types` workspace. Each application invokes that absent workspace in its `prebuild` script. Claiming a clean production build under those conditions would be fiction with a progress bar.
@@ -0,0 +1,40 @@
+# Phase 16 Operational UI Validation Report
+
+**Validated:** 2026-06-25  
+**Result:** Static migration gates passed
+
+## Passed checks
+
+| Check | Result |
+|---|---:|
+| Frontend/API source TypeScript and TSX parsed | 596 files, 0 syntax failures |
+| Admin/dashboard local and `@/` imports resolved | 190 imports, 0 unresolved |
+| Dashboard operational routes using Phase 16 heading/hero | 19 of 19 |
+| Admin operational routes using Phase 16 heading/hero | 12 of 12 |
+| Dashboard/admin token files present | Passed |
+| Shared sidebar, topbar, shell, panel, field, and action contracts present | Passed |
+| CSS brace balance | Passed |
+| Light/dark and Arabic RTL token mappings present | Passed |
+| Reduced-motion and forced-colors rules present | Passed |
+| Shared sign-in/create-account public layout retained | Passed |
+| Shared storefront navbar/footer components retained | Passed |
+| Retired `RentalDriveGo` brand in dashboard/admin source | 0 matches |
+| Complete app directories retained | `homepage`, `storefront`, `dashboard`, `admin`, `api` |
+
+## Reproducible design gate
+
+Run this from the extracted repository root:
+
+```bash
+node scripts/validate-phase16-design.mjs
+```
+
+Expected output:
+
+```text
+Phase 16 dashboard/admin design checks passed.
+```
+
+## Not claimed
+
+A production build, type-check against installed dependencies, integration test run, and browser visual regression run are not claimed. The supplied archive lacks the root workspace, root lockfile, `@rentaldrivego/types` package, and installed dependencies required by every application `prebuild` script.
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
@@ -0,0 +1,55 @@
+/** @type {import('next').NextConfig} */
+
+const { buildSecurityHeaders, normalizeAssetPrefix } = require('../../config/nextSecurityHeaders')
+const apiOrigin = (process.env.API_INTERNAL_URL ?? process.env.API_URL ?? 'http://localhost:4000').replace(/\/api\/v1\/?$/, '')
+const apiUrl = new URL(apiOrigin)
+const ADMIN_BASE_PATH = '/admin'
+
+// In Docker dev the admin app runs on port 3002 while the marketplace proxy
+// serves it from port 3000. When ADMIN_ASSET_PREFIX is set, Next emits
+// absolute chunk URLs so /admin pages load their JS/CSS and HMR directly from
+// port 3002, bypassing the proxy (which can't upgrade WebSocket connections).
+const assetPrefix = normalizeAssetPrefix(process.env.ADMIN_ASSET_PREFIX, ADMIN_BASE_PATH)
+const securityHeaders = buildSecurityHeaders({ assetSources: [assetPrefix] })
+
+const nextConfig = {
+  basePath: ADMIN_BASE_PATH,
+  ...(assetPrefix ? { assetPrefix } : {}),
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'res.cloudinary.com',
+      },
+      {
+        protocol: apiUrl.protocol.replace(':', ''),
+        hostname: apiUrl.hostname,
+        ...(apiUrl.port ? { port: apiUrl.port } : {}),
+        pathname: '/storage/**',
+      },
+    ],
+  },
+  transpilePackages: ['@rentaldrivego/types'],
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: securityHeaders,
+      },
+    ]
+  },
+  async rewrites() {
+    return [
+      {
+        source: '/api/:path*',
+        destination: `${apiOrigin}/api/:path*`,
+      },
+      {
+        source: '/storage/:path*',
+        destination: `${apiOrigin}/storage/:path*`,
+      },
+    ]
+  },
+}
+
+module.exports = nextConfig
@@ -0,0 +1,37 @@
+{
+  "name": "@rentaldrivego/admin",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "predev": "npm run build --workspace @rentaldrivego/types",
+    "dev": "next dev -H 0.0.0.0 -p 3002",
+    "prebuild": "npm run build --workspace @rentaldrivego/types",
+    "build": "next build",
+    "prestart": "npm run build --workspace @rentaldrivego/types",
+    "pretype-check": "npm run build --workspace @rentaldrivego/types",
+    "start": "next start -H 0.0.0.0 -p 3002",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@rentaldrivego/types": "*",
+    "autoprefixer": "^10.4.19",
+    "dayjs": "^1.11.11",
+    "lucide-react": "^0.376.0",
+    "next": "^16.2.7",
+    "postcss": "^8.4.38",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "recharts": "^2.12.7",
+    "tailwindcss": "^3.4.3",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}
@@ -0,0 +1,34 @@
+'use client'
+
+import { useEffect } from 'react'
+
+function resolveAdminNextPath(next: string | null) {
+  const fallback = '/admin/dashboard'
+  if (!next) return fallback
+
+  if (/^https?:\/\//i.test(next)) return next
+  if (next.startsWith('/admin/')) return next
+  if (next === '/admin') return '/admin/dashboard'
+  if (next.startsWith('/')) return `/admin${next}`
+
+  return `/admin/${next.replace(/^\/+/, '')}`
+}
+
+export default function AuthRedirectPage() {
+  useEffect(() => {
+    const hash = window.location.hash
+    const params = new URLSearchParams(hash.replace(/^#/, ''))
+    const next = resolveAdminNextPath(params.get('next'))
+
+    // Clear legacy token fragments from the URL. Admin auth now uses an HttpOnly cookie.
+    window.history.replaceState(null, '', window.location.pathname)
+
+    window.location.replace(next)
+  }, [])
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-zinc-950">
+      <p className="text-sm text-zinc-400">Redirecting to admin dashboard…</p>
+    </div>
+  )
+}
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { canAccessAdminMetrics } from './AdminSessionContext'
+
+describe('canAccessAdminMetrics', () => {
+  it('allows finance and higher roles after admin 2FA enrollment', () => {
+    expect(canAccessAdminMetrics({ role: 'FINANCE', totpEnabled: true })).toBe(true)
+    expect(canAccessAdminMetrics({ role: 'SUPPORT', totpEnabled: true })).toBe(true)
+    expect(canAccessAdminMetrics({ role: 'ADMIN', totpEnabled: true })).toBe(true)
+    expect(canAccessAdminMetrics({ role: 'SUPER_ADMIN', totpEnabled: true })).toBe(true)
+  })
+
+  it('denies viewer role and admins who still need 2FA enrollment', () => {
+    expect(canAccessAdminMetrics({ role: 'VIEWER', totpEnabled: true })).toBe(false)
+    expect(canAccessAdminMetrics({ role: 'ADMIN', totpEnabled: false })).toBe(false)
+    expect(canAccessAdminMetrics(null)).toBe(false)
+  })
+})
@@ -0,0 +1,34 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+
+export type AdminRole = 'SUPER_ADMIN' | 'ADMIN' | 'SUPPORT' | 'FINANCE' | 'VIEWER'
+
+export type AdminSessionUser = {
+  id: string
+  email: string
+  role: AdminRole
+  totpEnabled?: boolean
+}
+
+const METRICS_ALLOWED_ROLES = new Set<AdminRole>(['SUPER_ADMIN', 'ADMIN', 'SUPPORT', 'FINANCE'])
+
+const AdminSessionContext = createContext<AdminSessionUser | null>(null)
+
+export function AdminSessionProvider({
+  admin,
+  children,
+}: {
+  admin: AdminSessionUser
+  children: React.ReactNode
+}) {
+  return <AdminSessionContext.Provider value={admin}>{children}</AdminSessionContext.Provider>
+}
+
+export function useAdminSession() {
+  return useContext(AdminSessionContext)
+}
+
+export function canAccessAdminMetrics(admin: Pick<AdminSessionUser, 'role' | 'totpEnabled'> | null | undefined) {
+  return Boolean(admin && admin.totpEnabled && METRICS_ALLOWED_ROLES.has(admin.role))
+}
@@ -0,0 +1,277 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface AdminUser {
+  id: string
+  firstName: string
+  lastName: string
+  email: string
+  role: string
+  isActive: boolean
+  createdAt: string
+  permissions?: { id: string; resource: string; actions: string[] }[]
+}
+
+const ROLES = ['SUPER_ADMIN', 'ADMIN', 'SUPPORT', 'FINANCE', 'VIEWER']
+const EMPTY_FORM = {
+  firstName: '',
+  lastName: '',
+  email: '',
+  password: '',
+  role: 'SUPPORT',
+  isActive: true,
+}
+
+export default function AdminUsersPage() {
+  const [admins, setAdmins] = useState<AdminUser[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [showModal, setShowModal] = useState(false)
+  const [editingAdminId, setEditingAdminId] = useState<string | null>(null)
+  const [form, setForm] = useState(EMPTY_FORM)
+  const [saving, setSaving] = useState(false)
+
+  async function fetchAdmins() {
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/admins`, {
+        cache: 'no-store',
+        credentials: 'include',
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.message ?? 'Failed')
+      setAdmins(json.data ?? [])
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => { fetchAdmins() }, [])
+
+  function openCreateModal() {
+    setEditingAdminId(null)
+    setForm(EMPTY_FORM)
+    setError(null)
+    setShowModal(true)
+  }
+
+  function openEditModal(admin: AdminUser) {
+    setEditingAdminId(admin.id)
+    setForm({
+      firstName: admin.firstName,
+      lastName: admin.lastName,
+      email: admin.email,
+      password: '',
+      role: admin.role,
+      isActive: admin.isActive,
+    })
+    setError(null)
+    setShowModal(true)
+  }
+
+  function closeModal() {
+    setShowModal(false)
+    setEditingAdminId(null)
+    setForm(EMPTY_FORM)
+  }
+
+  async function saveAdmin(e: React.FormEvent) {
+    e.preventDefault()
+    setSaving(true)
+    setError(null)
+    try {
+      const isEditing = Boolean(editingAdminId)
+      const payload = {
+        firstName: form.firstName,
+        lastName: form.lastName,
+        email: form.email,
+        role: form.role,
+        isActive: form.isActive,
+        ...(form.password ? { password: form.password } : {}),
+      }
+
+      const res = await fetch(`${ADMIN_API_BASE}/admin/admins${editingAdminId ? `/${editingAdminId}` : ''}`, {
+        method: isEditing ? 'PATCH' : 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(payload),
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.message ?? `Failed to ${isEditing ? 'update' : 'create'} admin`)
+      closeModal()
+      await fetchAdmins()
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const ROLE_COLORS: Record<string, string> = {
+    SUPER_ADMIN: 'text-emerald-400 bg-emerald-950/40',
+    ADMIN: 'text-sky-400 bg-sky-950/40',
+    SUPPORT: 'text-orange-400 bg-orange-950/40',
+    FINANCE: 'text-violet-400 bg-violet-950/40',
+    VIEWER: 'text-zinc-400 bg-zinc-800',
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex items-center justify-between">
+        <div>
+          <p className="rdg-page-kicker">Platform</p>
+          <h1 className="mt-1 text-3xl font-black">Admin Users</h1>
+        </div>
+        <button
+          onClick={openCreateModal}
+          className="px-4 py-2 rounded-xl bg-emerald-700 hover:bg-blue-700 text-white text-sm font-semibold transition-colors"
+        >
+          + New admin
+        </button>
+      </div>
+
+      {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+
+      <div className="panel overflow-hidden">
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+                <tr className="border-b border-zinc-800">
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Name</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Email</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Role</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Permissions</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Status</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Joined</th>
+                  <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Actions</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr><td colSpan={7} className="px-6 py-12 text-center text-zinc-500">Loading…</td></tr>
+              ) : admins.length === 0 ? (
+                <tr><td colSpan={7} className="px-6 py-12 text-center text-zinc-500">No admin users found</td></tr>
+              ) : admins.map((a) => (
+                <tr key={a.id} className="hover:bg-zinc-800/30 transition-colors">
+                  <td className="px-6 py-4 font-medium text-zinc-100">{a.firstName} {a.lastName}</td>
+                  <td className="px-6 py-4 text-zinc-400">{a.email}</td>
+                  <td className="px-6 py-4">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${ROLE_COLORS[a.role] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {a.role}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4 text-xs text-zinc-500">
+                    {a.permissions && a.permissions.length > 0
+                      ? a.permissions.map((permission) => permission.resource).join(', ')
+                      : 'Role-based only'}
+                  </td>
+                  <td className="px-6 py-4">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${a.isActive ? 'text-emerald-400 bg-emerald-950/40' : 'text-zinc-500 bg-zinc-800'}`}>
+                      {a.isActive ? 'Active' : 'Inactive'}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4 text-zinc-500 text-xs">{new Date(a.createdAt).toLocaleDateString()}</td>
+                  <td className="px-6 py-4">
+                    <button
+                      type="button"
+                      onClick={() => openEditModal(a)}
+                      className="rounded-lg border border-zinc-700 px-3 py-1.5 text-xs font-medium text-zinc-300 transition-colors hover:border-zinc-500 hover:text-white"
+                    >
+                      Edit
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      {showModal && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-[#07101e]/60 backdrop-blur-sm">
+          <div className="w-full max-w-md rounded-2xl border border-zinc-700 bg-zinc-900 p-8 shadow-2xl">
+            <div className="flex items-center justify-between mb-6">
+              <h2 className="text-lg font-semibold">{editingAdminId ? 'Edit admin user' : 'New admin user'}</h2>
+              <button onClick={closeModal} className="text-zinc-500 hover:text-zinc-200">✕</button>
+            </div>
+            <form onSubmit={saveAdmin} className="space-y-4">
+              <div className="grid grid-cols-2 gap-4">
+                <div>
+                  <label className="block text-xs font-medium text-zinc-400 mb-1">First name</label>
+                  <input
+                    required
+                    className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                    value={form.firstName}
+                    onChange={(e) => setForm({ ...form, firstName: e.target.value })}
+                  />
+                </div>
+                <div>
+                  <label className="block text-xs font-medium text-zinc-400 mb-1">Last name</label>
+                  <input
+                    required
+                    className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                    value={form.lastName}
+                    onChange={(e) => setForm({ ...form, lastName: e.target.value })}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className="block text-xs font-medium text-zinc-400 mb-1">Email</label>
+                <input
+                  type="email"
+                  required
+                  className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                  value={form.email}
+                  onChange={(e) => setForm({ ...form, email: e.target.value })}
+                />
+              </div>
+              <div>
+                <label className="block text-xs font-medium text-zinc-400 mb-1">
+                  Password {editingAdminId ? <span className="text-zinc-500">(leave blank to keep current)</span> : null}
+                </label>
+                <input
+                  type="password"
+                  required={!editingAdminId}
+                  minLength={editingAdminId ? undefined : 8}
+                  className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                  value={form.password}
+                  onChange={(e) => setForm({ ...form, password: e.target.value })}
+                />
+              </div>
+              <div>
+                <label className="block text-xs font-medium text-zinc-400 mb-1">Role</label>
+                <select
+                  className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                  value={form.role}
+                  onChange={(e) => setForm({ ...form, role: e.target.value })}
+                >
+                  {ROLES.map((r) => <option key={r} value={r}>{r}</option>)}
+                </select>
+              </div>
+              <div>
+                <label className="block text-xs font-medium text-zinc-400 mb-1">Status</label>
+                <select
+                  className="w-full px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm focus:outline-none focus:ring-2 focus:ring-orange-500"
+                  value={form.isActive ? 'active' : 'inactive'}
+                  onChange={(e) => setForm({ ...form, isActive: e.target.value === 'active' })}
+                >
+                  <option value="active">Active</option>
+                  <option value="inactive">Inactive</option>
+                </select>
+              </div>
+              <div className="flex gap-3 pt-2">
+                <button type="button" onClick={closeModal} className="flex-1 py-2.5 rounded-xl bg-zinc-800 text-zinc-300 text-sm font-medium">Cancel</button>
+                <button type="submit" disabled={saving} className="flex-1 py-2.5 rounded-xl bg-emerald-700 hover:bg-blue-700 text-white text-sm font-semibold disabled:opacity-50">
+                  {saving ? (editingAdminId ? 'Saving…' : 'Creating…') : (editingAdminId ? 'Save changes' : 'Create admin')}
+                </button>
+              </div>
+            </form>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
@@ -0,0 +1,98 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface AuditLog {
+  id: string
+  action: string
+  resource: string
+  resourceId: string | null
+  createdAt: string
+  adminUser: { email: string; firstName: string; lastName: string } | null
+}
+
+const ACTION_COLORS: Record<string, string> = {
+  CREATE: 'text-emerald-400 bg-emerald-950/40',
+  UPDATE: 'text-sky-400 bg-sky-950/40',
+  DELETE: 'text-red-400 bg-red-950/40',
+  SUSPEND: 'text-orange-400 bg-orange-950/40',
+  ACTIVATE: 'text-emerald-400 bg-emerald-950/40',
+  LOGIN: 'text-zinc-400 bg-zinc-800',
+}
+
+export default function AdminAuditLogsPage() {
+  const [logs, setLogs] = useState<AuditLog[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [filter, setFilter] = useState('')
+
+  useEffect(() => {
+    fetch(`${ADMIN_API_BASE}/admin/audit-logs`, {
+      credentials: 'include',
+      cache: 'no-store',
+    })
+      .then((r) => r.json())
+      .then((json) => setLogs(Array.isArray(json.data) ? json.data : (json.data?.data ?? [])))
+      .catch((err) => setError(err.message))
+      .finally(() => setLoading(false))
+  }, [])
+
+  const filtered = filter
+    ? logs.filter((l) => l.action.toLowerCase().includes(filter.toLowerCase()) || l.resource.toLowerCase().includes(filter.toLowerCase()))
+    : logs
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex items-center justify-between">
+        <div>
+          <p className="rdg-page-kicker">Platform</p>
+          <h1 className="mt-1 text-3xl font-black">Audit Logs</h1>
+        </div>
+        <input
+          className="w-64 px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm placeholder:text-zinc-500 focus:outline-none focus:ring-2 focus:ring-orange-500"
+          placeholder="Filter by action or entity…"
+          value={filter}
+          onChange={(e) => setFilter(e.target.value)}
+        />
+      </div>
+
+      {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+
+      <div className="panel overflow-hidden">
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800">
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Action</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Entity</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Entity ID</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Admin</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">Time</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr><td colSpan={5} className="px-6 py-12 text-center text-zinc-500">Loading…</td></tr>
+              ) : filtered.length === 0 ? (
+                <tr><td colSpan={5} className="px-6 py-12 text-center text-zinc-500">No logs found</td></tr>
+              ) : filtered.map((log) => (
+                <tr key={log.id} className="hover:bg-zinc-800/30 transition-colors">
+                  <td className="px-6 py-3">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${ACTION_COLORS[log.action] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {log.action}
+                    </span>
+                  </td>
+                  <td className="px-6 py-3 text-zinc-300">{log.resource}</td>
+                  <td className="px-6 py-3 text-zinc-500 font-mono text-xs">{log.resourceId ? `${log.resourceId.slice(0, 12)}…` : '—'}</td>
+                  <td className="px-6 py-3 text-zinc-400">{log.adminUser ? `${log.adminUser.firstName} ${log.adminUser.lastName}` : '—'}</td>
+                  <td className="px-6 py-3 text-zinc-500 text-xs">{new Date(log.createdAt).toLocaleString()}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,213 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import Link from 'next/link'
+import { useAdminI18n } from '@/components/I18nProvider'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface Company {
+  id: string
+  name: string
+  slug: string
+  status: string
+  email: string
+  contractSettings: { legalName: string | null } | null
+  subscription: { plan: string; status: string } | null
+  _count: { employees: number; vehicles: number }
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  ACTIVE: 'text-emerald-400 bg-emerald-900/30',
+  TRIALING: 'text-sky-400 bg-sky-900/30',
+  SUSPENDED: 'text-red-400 bg-red-900/30',
+  PENDING: 'text-orange-400 bg-orange-900/30',
+  CANCELLED: 'text-zinc-400 bg-zinc-800',
+}
+
+export default function AdminCompaniesPage() {
+  const { language, dict } = useAdminI18n()
+  const copy = {
+    en: {
+      title: 'Companies',
+      search: 'Search by name or slug…',
+      loading: 'Loading…',
+      empty: 'No companies found',
+      company: 'Company',
+      legalName: 'Legal name',
+      slug: 'Slug',
+      status: 'Status',
+      plan: 'Plan',
+      fleet: 'Fleet',
+      vehicles: 'vehicles',
+      view: 'View',
+      suspend: 'Suspend',
+      reactivate: 'Reactivate',
+    },
+    fr: {
+      title: 'Entreprises',
+      search: 'Rechercher par nom ou slug…',
+      loading: 'Chargement…',
+      empty: 'Aucune entreprise trouvée',
+      company: 'Entreprise',
+      legalName: 'Raison sociale',
+      slug: 'Slug',
+      status: 'Statut',
+      plan: 'Plan',
+      fleet: 'Flotte',
+      vehicles: 'véhicules',
+      view: 'Voir',
+      suspend: 'Suspendre',
+      reactivate: 'Réactiver',
+    },
+    ar: {
+      title: 'الشركات',
+      search: 'ابحث بالاسم أو بالمُعرّف المختصر…',
+      loading: 'جارٍ التحميل…',
+      empty: 'لم يتم العثور على شركات',
+      company: 'الشركة',
+      legalName: 'الاسم القانوني',
+      slug: 'Slug',
+      status: 'الحالة',
+      plan: 'الخطة',
+      fleet: 'الأسطول',
+      vehicles: 'مركبة',
+      view: 'عرض',
+      suspend: 'تعليق',
+      reactivate: 'إعادة التفعيل',
+    },
+  }[language]
+  const [companies, setCompanies] = useState<Company[]>([])
+  const [filtered, setFiltered] = useState<Company[]>([])
+  const [search, setSearch] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [actioning, setActioning] = useState<string | null>(null)
+
+  async function fetchCompanies() {
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/companies`, {
+        credentials: 'include',
+        cache: 'no-store',
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.message ?? 'Failed to fetch')
+      const list = Array.isArray(json.data) ? json.data : (json.data?.data ?? [])
+      setCompanies(list)
+      setFiltered(list)
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => { fetchCompanies() }, [])
+
+  useEffect(() => {
+    const q = search.toLowerCase()
+    setFiltered(companies.filter((c) => c.name.toLowerCase().includes(q) || c.slug.includes(q) || c.email.toLowerCase().includes(q)))
+  }, [search, companies])
+
+  async function changeStatus(id: string, status: string) {
+    setActioning(id)
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/companies/${id}/status`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify({ status }),
+      })
+      if (!res.ok) throw new Error('Action failed')
+      await fetchCompanies()
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setActioning(null)
+    }
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex items-center justify-between">
+        <div>
+          <p className="rdg-page-kicker">{dict.platform}</p>
+          <h1 className="mt-1 text-3xl font-black">{copy.title}</h1>
+        </div>
+        <input
+          className="w-64 px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm placeholder:text-zinc-500 focus:outline-none focus:ring-2 focus:ring-orange-500"
+          placeholder={copy.search}
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+        />
+      </div>
+
+      {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+
+      <div className="panel overflow-hidden">
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800">
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.company}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.slug}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.status}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.plan}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.fleet}</th>
+                <th className="px-6 py-3" />
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr><td colSpan={6} className="px-6 py-12 text-center text-zinc-500">{copy.loading}</td></tr>
+              ) : filtered.length === 0 ? (
+                <tr><td colSpan={6} className="px-6 py-12 text-center text-zinc-500">{copy.empty}</td></tr>
+              ) : filtered.map((c) => (
+                <tr key={c.id} className="hover:bg-zinc-800/30 transition-colors">
+                  <td className="px-6 py-4">
+                    <p className="font-medium text-zinc-100">{c.name}</p>
+                    {c.contractSettings?.legalName && c.contractSettings.legalName !== c.name ? (
+                      <p className="text-xs text-zinc-400">{copy.legalName}: {c.contractSettings.legalName}</p>
+                    ) : null}
+                    <p className="text-xs text-zinc-500">{c.email}</p>
+                  </td>
+                  <td className="px-6 py-4 text-zinc-400 font-mono text-xs">{c.slug}</td>
+                  <td className="px-6 py-4">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${STATUS_COLORS[c.status] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {c.status}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4 text-zinc-400">{c.subscription?.plan ?? '—'}</td>
+                  <td className="px-6 py-4 text-zinc-400">{c._count?.vehicles ?? 0} {copy.vehicles}</td>
+                  <td className="px-6 py-4">
+                    <div className="flex items-center gap-2 justify-end">
+                      <Link href={`/dashboard/companies/${c.id}`} className="px-3 py-1.5 rounded-lg bg-zinc-800 hover:bg-zinc-700 text-xs font-medium text-zinc-200 transition-colors">
+                        {copy.view}
+                      </Link>
+                      {c.status === 'ACTIVE' || c.status === 'TRIALING' ? (
+                        <button
+                          onClick={() => changeStatus(c.id, 'SUSPENDED')}
+                          disabled={actioning === c.id}
+                          className="px-3 py-1.5 rounded-lg bg-red-950/50 hover:bg-red-900/50 text-xs font-medium text-red-400 transition-colors disabled:opacity-50"
+                        >
+                          {copy.suspend}
+                        </button>
+                      ) : c.status === 'SUSPENDED' ? (
+                        <button
+                          onClick={() => changeStatus(c.id, 'ACTIVE')}
+                          disabled={actioning === c.id}
+                          className="px-3 py-1.5 rounded-lg bg-emerald-950/50 hover:bg-emerald-900/50 text-xs font-medium text-emerald-400 transition-colors disabled:opacity-50"
+                        >
+                          {copy.reactivate}
+                        </button>
+                      ) : null}
+                    </div>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,435 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+type ContainerStatus = 'PENDING' | 'CREATING' | 'RUNNING' | 'STOPPED' | 'RESTARTING' | 'REMOVING' | 'ERROR'
+
+interface CompanyContainer {
+  id: string
+  companyId: string
+  dockerId: string | null
+  containerName: string
+  status: ContainerStatus
+  port: number
+  image: string
+  errorMessage: string | null
+  createdAt: string
+  updatedAt: string
+  company: {
+    id: string
+    name: string
+    slug: string
+    status: string
+  }
+}
+
+function authHeaders() {
+  return { 'Content-Type': 'application/json' }
+}
+
+function StatusBadge({ status }: { status: ContainerStatus }) {
+  const map: Record<ContainerStatus, { label: string; className: string }> = {
+    PENDING:    { label: 'Pending',    className: 'bg-zinc-700 text-zinc-300' },
+    CREATING:   { label: 'Creating…',  className: 'bg-blue-900 text-blue-300 animate-pulse' },
+    RUNNING:    { label: 'Running',    className: 'bg-emerald-900 text-emerald-300' },
+    STOPPED:    { label: 'Stopped',    className: 'bg-orange-900 text-orange-300' },
+    RESTARTING: { label: 'Restarting…',className: 'bg-orange-900 text-orange-300 animate-pulse' },
+    REMOVING:   { label: 'Removing…',  className: 'bg-red-900 text-red-300 animate-pulse' },
+    ERROR:      { label: 'Error',      className: 'bg-red-950 text-red-400' },
+  }
+  const { label, className } = map[status] ?? map.ERROR
+  return (
+    <span className={`inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-xs font-medium ${className}`}>
+      <span className={`h-1.5 w-1.5 rounded-full ${status === 'RUNNING' ? 'bg-emerald-400' : 'bg-current opacity-60'}`} />
+      {label}
+    </span>
+  )
+}
+
+function LogsModal({ companyId, companyName, onClose }: { companyId: string; companyName: string; onClose: () => void }) {
+  const [logs, setLogs] = useState<string>('')
+  const [loading, setLoading] = useState(true)
+  const [tail, setTail] = useState(150)
+  const bottomRef = useRef<HTMLDivElement>(null)
+
+  const fetchLogs = useCallback(async (lines: number) => {
+    setLoading(true)
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/containers/${companyId}/logs?tail=${lines}`, { headers: authHeaders(), credentials: 'include' })
+      const json = await res.json()
+      setLogs(json.data?.logs ?? '')
+    } catch {
+      setLogs('Failed to fetch logs.')
+    } finally {
+      setLoading(false)
+    }
+  }, [companyId])
+
+  useEffect(() => { fetchLogs(tail) }, [fetchLogs, tail])
+  useEffect(() => { bottomRef.current?.scrollIntoView() }, [logs])
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-[#07101e]/70 p-4" onClick={onClose}>
+      <div className="flex h-[80vh] w-full max-w-4xl flex-col rounded-2xl border border-zinc-700 bg-zinc-900 shadow-2xl" onClick={(e) => e.stopPropagation()}>
+        <div className="flex items-center justify-between border-b border-zinc-700 px-5 py-4">
+          <div>
+            <p className="text-sm font-semibold text-zinc-100">Container Logs</p>
+            <p className="text-xs text-zinc-400">{companyName}</p>
+          </div>
+          <div className="flex items-center gap-3">
+            <select
+              value={tail}
+              onChange={(e) => setTail(Number(e.target.value))}
+              className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-200 focus:outline-none"
+            >
+              <option value={50}>Last 50 lines</option>
+              <option value={150}>Last 150 lines</option>
+              <option value={500}>Last 500 lines</option>
+              <option value={1000}>Last 1000 lines</option>
+            </select>
+            <button onClick={() => fetchLogs(tail)} className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-700">
+              Refresh
+            </button>
+            <button onClick={onClose} className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 hover:bg-zinc-700">
+              Close
+            </button>
+          </div>
+        </div>
+        <div className="flex-1 overflow-y-auto p-4">
+          {loading ? (
+            <p className="text-xs text-zinc-500">Loading…</p>
+          ) : (
+            <pre className="whitespace-pre-wrap break-all font-mono text-xs leading-relaxed text-zinc-300">
+              {logs || 'No logs available.'}
+            </pre>
+          )}
+          <div ref={bottomRef} />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+type ProvisionResult = { companyId: string; name: string; status: 'created' | 'error'; error?: string }
+
+export default function ContainersPage() {
+  const [containers, setContainers] = useState<CompanyContainer[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState<Record<string, boolean>>({})
+  const [logsFor, setLogsFor] = useState<{ companyId: string; companyName: string } | null>(null)
+  const [search, setSearch] = useState('')
+  const [provisioning, setProvisioning] = useState(false)
+  const [provisionResults, setProvisionResults] = useState<ProvisionResult[] | null>(null)
+
+  const fetchContainers = useCallback(async () => {
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/containers`, { headers: authHeaders(), credentials: 'include' })
+      const json = await res.json().catch(() => null)
+      if (!res.ok) {
+        throw new Error(json?.message ?? 'Failed to load containers.')
+      }
+      setContainers(json.data ?? [])
+      setError(null)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load containers.')
+      /* silent — keep old data */
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    fetchContainers()
+    const id = setInterval(fetchContainers, 8000)
+    return () => clearInterval(id)
+  }, [fetchContainers])
+
+  async function provisionAll() {
+    setProvisioning(true)
+    setProvisionResults(null)
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/containers/provision-all`, { method: 'POST', headers: authHeaders(), credentials: 'include' })
+      const json = await res.json().catch(() => null)
+      if (!res.ok) throw new Error(json?.message ?? 'Provisioning failed.')
+      setProvisionResults(json.data?.results ?? [])
+      setError(null)
+      await fetchContainers()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Provisioning failed.')
+    } finally {
+      setProvisioning(false)
+    }
+  }
+
+  async function act(companyId: string, action: 'start' | 'stop' | 'restart' | 'deploy' | 'remove') {
+    setBusy((b) => ({ ...b, [companyId]: true }))
+    try {
+      const method = action === 'remove' ? 'DELETE' : 'POST'
+      const url =
+        action === 'remove'
+          ? `${ADMIN_API_BASE}/admin/containers/${companyId}`
+          : `${ADMIN_API_BASE}/admin/containers/${companyId}/${action}`
+      const res = await fetch(url, { method, headers: authHeaders(), credentials: 'include' })
+      const json = await res.json().catch(() => null)
+      if (!res.ok) {
+        throw new Error(json?.message ?? `Failed to ${action} container.`)
+      }
+      setError(null)
+      await fetchContainers()
+    } catch (err) {
+      setError(err instanceof Error ? err.message : `Failed to ${action} container.`)
+    } finally {
+      setBusy((b) => ({ ...b, [companyId]: false }))
+    }
+  }
+
+  const filtered = containers.filter(
+    (c) =>
+      c.company.name.toLowerCase().includes(search.toLowerCase()) ||
+      c.containerName.toLowerCase().includes(search.toLowerCase()) ||
+      c.company.slug.toLowerCase().includes(search.toLowerCase()),
+  )
+
+  const stats = {
+    running: containers.filter((c) => c.status === 'RUNNING').length,
+    stopped: containers.filter((c) => c.status === 'STOPPED').length,
+    error: containers.filter((c) => c.status === 'ERROR').length,
+    total: containers.length,
+  }
+
+  return (
+    <div className="space-y-6">
+      {logsFor && (
+        <LogsModal
+          companyId={logsFor.companyId}
+          companyName={logsFor.companyName}
+          onClose={() => setLogsFor(null)}
+        />
+      )}
+
+      <div className="rdg-page-heading mb-8 flex items-start justify-between">
+        <div>
+          <h1 className="text-xl font-semibold text-zinc-100">Containers</h1>
+          <p className="mt-1 text-sm text-zinc-400">Manage isolated Docker Compose services for each company workspace.</p>
+        </div>
+        <button
+          onClick={provisionAll}
+          disabled={provisioning}
+          className="flex items-center gap-2 rounded-xl bg-emerald-700 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-50 transition-colors"
+        >
+          {provisioning ? (
+            <>
+              <span className="h-4 w-4 animate-spin rounded-full border-2 border-white border-t-transparent" />
+              Provisioning…
+            </>
+          ) : (
+            <>
+              <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M5.25 5.653c0-.856.917-1.398 1.667-.986l11.54 6.347a1.125 1.125 0 0 1 0 1.972l-11.54 6.347a1.125 1.125 0 0 1-1.667-.986V5.653Z" />
+              </svg>
+              Provision All Accounts
+            </>
+          )}
+        </button>
+      </div>
+
+      {error && (
+        <div className="mb-6 rounded-xl border border-red-900 bg-red-950/70 px-4 py-3 text-sm text-red-200">
+          {error}
+        </div>
+      )}
+
+      {provisionResults !== null && (
+        <div className="panel mb-6 p-4">
+          <div className="mb-3 flex items-center justify-between">
+            <p className="text-sm font-medium text-zinc-200">
+              Provisioning complete —{' '}
+              <span className="text-emerald-400">{provisionResults.filter((r) => r.status === 'created').length} created</span>
+              {provisionResults.some((r) => r.status === 'error') && (
+                <>, <span className="text-red-400">{provisionResults.filter((r) => r.status === 'error').length} failed</span></>
+              )}
+            </p>
+            <button onClick={() => setProvisionResults(null)} className="text-xs text-zinc-500 hover:text-zinc-300">Dismiss</button>
+          </div>
+          <div className="space-y-1.5 max-h-48 overflow-y-auto">
+            {provisionResults.map((r) => (
+              <div key={r.companyId} className="flex items-center gap-3 rounded-lg px-3 py-2 bg-zinc-800/60">
+                <span className={`h-1.5 w-1.5 flex-shrink-0 rounded-full ${r.status === 'created' ? 'bg-emerald-400' : 'bg-red-400'}`} />
+                <span className="text-sm text-zinc-300 flex-1">{r.name}</span>
+                {r.status === 'error' && <span className="text-xs text-red-400 truncate max-w-xs">{r.error}</span>}
+                {r.status === 'created' && <span className="text-xs text-emerald-500">Service created</span>}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Stats */}
+      <div className="mb-6 grid grid-cols-4 gap-4">
+        {[
+          { label: 'Total', value: stats.total, color: 'text-zinc-100' },
+          { label: 'Running', value: stats.running, color: 'text-emerald-400' },
+          { label: 'Stopped', value: stats.stopped, color: 'text-orange-400' },
+          { label: 'Error', value: stats.error, color: 'text-red-400' },
+        ].map((s) => (
+          <div key={s.label} className="panel p-4">
+            <p className="text-xs text-zinc-500">{s.label}</p>
+            <p className={`mt-1 text-2xl font-bold ${s.color}`}>{s.value}</p>
+          </div>
+        ))}
+      </div>
+
+      {/* Search */}
+      <div className="mb-4">
+        <input
+          type="text"
+          placeholder="Search by company name or container…"
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+          className="w-full max-w-sm rounded-xl border border-zinc-700 bg-zinc-800 px-4 py-2 text-sm text-zinc-200 placeholder-zinc-500 focus:outline-none focus:ring-1 focus:ring-orange-500"
+        />
+      </div>
+
+      {/* Table */}
+      <div className="panel overflow-hidden">
+        {loading ? (
+          <div className="flex items-center justify-center py-16">
+            <div className="h-6 w-6 animate-spin rounded-full border-2 border-emerald-500 border-t-transparent" />
+          </div>
+        ) : filtered.length === 0 ? (
+          <div className="py-16 text-center text-sm text-zinc-500">
+            {search ? 'No containers match your search.' : 'No containers yet. They are created automatically on company signup.'}
+          </div>
+        ) : (
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800 text-left text-xs text-zinc-500">
+                <th className="px-5 py-3 font-medium">Company</th>
+                <th className="px-5 py-3 font-medium">Container</th>
+                <th className="px-5 py-3 font-medium">Status</th>
+                <th className="px-5 py-3 font-medium">Port</th>
+                <th className="px-5 py-3 font-medium">Image</th>
+                <th className="px-5 py-3 font-medium">Actions</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800">
+              {filtered.map((c) => {
+                const isBusy = busy[c.companyId] ?? false
+                const isRunning = c.status === 'RUNNING'
+                const isStopped = c.status === 'STOPPED' || c.status === 'ERROR'
+                const isTransitioning = ['CREATING', 'RESTARTING', 'REMOVING'].includes(c.status)
+
+                return (
+                  <tr key={c.id} className="hover:bg-zinc-800/40">
+                    <td className="px-5 py-4">
+                      <p className="font-medium text-zinc-100">{c.company.name}</p>
+                      <p className="text-xs text-zinc-500">{c.company.slug}</p>
+                      {c.errorMessage && (
+                        <p className="mt-1 text-xs text-red-400" title={c.errorMessage}>
+                          {c.errorMessage.slice(0, 60)}{c.errorMessage.length > 60 ? '…' : ''}
+                        </p>
+                      )}
+                    </td>
+                    <td className="px-5 py-4 font-mono text-xs text-zinc-400">
+                      {c.containerName}
+                      {c.dockerId && (
+                        <p className="mt-0.5 text-zinc-600">{c.dockerId.slice(0, 12)}</p>
+                      )}
+                    </td>
+                    <td className="px-5 py-4">
+                      <StatusBadge status={c.status} />
+                    </td>
+                    <td className="px-5 py-4 font-mono text-xs text-zinc-400">:{c.port}</td>
+                    <td className="px-5 py-4 font-mono text-xs text-zinc-500">{c.image}</td>
+                    <td className="px-5 py-4">
+                      <div className="flex items-center gap-1.5">
+                        {isStopped && (
+                          <ActionButton
+                            label="Start"
+                            color="emerald"
+                            disabled={isBusy || isTransitioning}
+                            onClick={() => act(c.companyId, 'start')}
+                          />
+                        )}
+                        {isRunning && (
+                          <ActionButton
+                            label="Stop"
+                            color="yellow"
+                            disabled={isBusy || isTransitioning}
+                            onClick={() => act(c.companyId, 'stop')}
+                          />
+                        )}
+                        {(isRunning || isStopped) && (
+                          <ActionButton
+                            label="Restart"
+                            color="blue"
+                            disabled={isBusy || isTransitioning}
+                            onClick={() => act(c.companyId, 'restart')}
+                          />
+                        )}
+                        <ActionButton
+                          label="Redeploy"
+                          color="purple"
+                          disabled={isBusy || isTransitioning}
+                          onClick={() => act(c.companyId, 'deploy')}
+                        />
+                        <ActionButton
+                          label="Logs"
+                          color="zinc"
+                          disabled={isBusy || !c.dockerId}
+                          onClick={() => setLogsFor({ companyId: c.companyId, companyName: c.company.name })}
+                        />
+                        <ActionButton
+                          label="Remove"
+                          color="red"
+                          disabled={isBusy || isTransitioning}
+                          onClick={() => {
+                            if (confirm(`Remove container for ${c.company.name}? This cannot be undone.`)) {
+                              act(c.companyId, 'remove')
+                            }
+                          }}
+                        />
+                      </div>
+                    </td>
+                  </tr>
+                )
+              })}
+            </tbody>
+          </table>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function ActionButton({
+  label,
+  color,
+  disabled,
+  onClick,
+}: {
+  label: string
+  color: 'emerald' | 'yellow' | 'blue' | 'purple' | 'zinc' | 'red'
+  disabled: boolean
+  onClick: () => void
+}) {
+  const colorMap: Record<string, string> = {
+    emerald: 'border-emerald-800 text-emerald-400 hover:bg-emerald-900/40',
+    yellow:  'border-orange-800 text-orange-400 hover:bg-orange-900/40',
+    blue:    'border-blue-800 text-blue-400 hover:bg-blue-900/40',
+    purple:  'border-purple-800 text-purple-400 hover:bg-purple-900/40',
+    zinc:    'border-zinc-700 text-zinc-400 hover:bg-zinc-700/40',
+    red:     'border-red-900 text-red-400 hover:bg-red-900/30',
+  }
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled}
+      className={`rounded-lg border px-2.5 py-1 text-xs font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-40 ${colorMap[color]}`}
+    >
+      {label}
+    </button>
+  )
+}
@@ -0,0 +1,241 @@
+'use client'
+
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+import { useEffect, useMemo, useState } from 'react'
+import {
+  AdminLanguageSwitcher,
+  AdminThemeSwitcher,
+  useAdminI18n,
+} from '@/components/I18nProvider'
+import { resolveBrowserAppUrl } from '@/lib/appUrls'
+import { ADMIN_API_BASE } from '@/lib/api'
+import { AdminSessionProvider, type AdminSessionUser } from './AdminSessionContext'
+
+function buildUnifiedLoginUrl(nextPath: string) {
+  const dashboardUrl = resolveBrowserAppUrl(process.env.NEXT_PUBLIC_DASHBOARD_URL ?? 'http://localhost:3000/dashboard')
+  const params = new URLSearchParams({
+    portal: 'admin',
+    next: nextPath || '/dashboard',
+  })
+  return `${dashboardUrl}/sign-in?${params.toString()}`
+}
+
+const navLinks = [
+  { href: '/dashboard', key: 'overview', icon: 'M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6' },
+  { href: '/dashboard/companies', key: 'companies', icon: 'M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4' },
+  { href: '/dashboard/site-config', key: 'siteConfig', icon: 'M4.5 12a7.5 7.5 0 1015 0 7.5 7.5 0 00-15 0zm7.5-4.5v4.5l3 3' },
+  { href: '/dashboard/renters', key: 'renters', icon: 'M17 20h5v-2a3 3 0 00-5.356-1.857M17 20H7m10 0v-2c0-.656-.126-1.283-.356-1.857M7 20H2v-2a3 3 0 015.356-1.857M7 20v-2c0-.656.126-1.283.356-1.857m0 0a5.002 5.002 0 019.288 0M15 7a3 3 0 11-6 0 3 3 0 016 0z' },
+  { href: '/dashboard/audit-logs', key: 'auditLogs', icon: 'M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z' },
+  { href: '/dashboard/notifications', key: 'notifications', icon: 'M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9' },
+  { href: '/dashboard/menu-management', key: 'menuManagement', icon: 'M4 6h16M4 12h16M4 18h10' },
+  { href: '/dashboard/admin-users', key: 'adminUsers', icon: 'M12 4.354a4 4 0 110 5.292M15 21H3v-1a6 6 0 0112 0v1zm0 0h6v-1a6 6 0 00-9-5.197M13 7a4 4 0 11-8 0 4 4 0 018 0z' },
+  { href: '/dashboard/billing', key: 'billing', icon: 'M3 10h18M7 15h1m4 0h1m-7 4h12a3 3 0 003-3V8a3 3 0 00-3-3H6a3 3 0 00-3 3v8a3 3 0 003 3z' },
+  { href: '/dashboard/pricing', key: 'pricing', icon: 'M12 8c-1.657 0-3 .895-3 2s1.343 2 3 2 3 .895 3 2-1.343 2-3 2m0-8c1.11 0 2.08.402 2.599 1M12 8V7m0 1v8m0 0v1m0-1c-1.11 0-2.08-.402-2.599-1M21 12a9 9 0 11-18 0 9 9 0 0118 0z' },
+] as const
+
+function adminInitials(email: string | undefined) {
+  if (!email) return 'A'
+  return email.split('@')[0].split(/[._-]+/).filter(Boolean).slice(0, 2).map((part) => part[0]?.toUpperCase()).join('') || 'A'
+}
+
+export default function AdminDashboardLayout({ children }: { children: React.ReactNode }) {
+  const { dict, language } = useAdminI18n()
+  const pathname = usePathname()
+  const [ready, setReady] = useState(false)
+  const [admin, setAdmin] = useState<AdminSessionUser | null>(null)
+  const [navigationOpen, setNavigationOpen] = useState(false)
+  const isRtl = language === 'ar'
+
+  const activeNavigation = useMemo(
+    () => [...navLinks]
+      .sort((a, b) => b.href.length - a.href.length)
+      .find((link) => pathname === link.href || (link.href !== '/dashboard' && pathname.startsWith(link.href))),
+    [pathname],
+  )
+  const pageTitle = activeNavigation ? dict.nav[activeNavigation.key] : dict.overview
+
+  useEffect(() => {
+    let cancelled = false
+
+    fetch(`${ADMIN_API_BASE}/admin/auth/me`, {
+      credentials: 'include',
+    })
+      .then(async (response) => {
+        if (cancelled) return
+        if (response.ok) {
+          const json = await response.json().catch(() => null)
+          const resolvedAdmin = (json?.data ?? json) as AdminSessionUser | null
+          if (!resolvedAdmin?.id || !resolvedAdmin?.email || !resolvedAdmin?.role) {
+            window.location.replace(buildUnifiedLoginUrl(pathname))
+            return
+          }
+          setAdmin(resolvedAdmin)
+          setReady(true)
+        } else {
+          window.location.replace(buildUnifiedLoginUrl(pathname))
+        }
+      })
+      .catch(() => {
+        if (!cancelled) window.location.replace(buildUnifiedLoginUrl(pathname))
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [pathname])
+
+  useEffect(() => {
+    setNavigationOpen(false)
+  }, [pathname])
+
+  function handleLogout() {
+    void fetch('/admin/api/v1/admin/auth/logout', { method: 'POST', credentials: 'include' })
+    window.location.href = buildUnifiedLoginUrl('/dashboard')
+  }
+
+  if (!ready) {
+    return (
+      <div className="rdg-app-shell flex min-h-screen items-center justify-center">
+        <div
+          className="h-8 w-8 animate-spin rounded-full border-2 border-[var(--rdg-action-primary)] border-t-[var(--rdg-action-conversion)]"
+          aria-label={dict.loading}
+        />
+      </div>
+    )
+  }
+
+  const navigation = (
+    <>
+      <Link
+        href="/dashboard"
+        className="rdg-sidebar-brand flex min-h-[76px] items-center gap-3 border-b border-[var(--rdg-border)] px-5"
+      >
+        <span className="rdg-brand-mark text-xs font-black">RDG</span>
+        <span className="min-w-0">
+          <span className="block text-[0.68rem] font-bold uppercase tracking-[0.2em] text-[var(--rdg-action-conversion)]">
+            {dict.admin}
+          </span>
+          <span className="mt-0.5 block truncate text-sm font-extrabold text-[var(--rdg-text-primary)]">
+            RentalDriveGo
+          </span>
+        </span>
+      </Link>
+
+      <nav className="rdg-sidebar-nav flex-1 space-y-1 overflow-y-auto px-3 py-4" aria-label={dict.admin}>
+        {navLinks.map((link) => {
+          const active = pathname === link.href || (link.href !== '/dashboard' && pathname.startsWith(link.href))
+          return (
+            <Link
+              key={link.href}
+              href={link.href}
+              aria-current={active ? 'page' : undefined}
+              data-active={active ? 'true' : 'false'}
+              className="rdg-nav-item flex items-center gap-3 px-3 py-2.5 text-sm font-semibold"
+            >
+              <svg
+                className="h-4 w-4 flex-shrink-0"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={1.7}
+                aria-hidden="true"
+              >
+                <path strokeLinecap="round" strokeLinejoin="round" d={link.icon} />
+              </svg>
+              <span>{dict.nav[link.key]}</span>
+            </Link>
+          )
+        })}
+      </nav>
+
+      <div className="rdg-sidebar-footer border-t border-[var(--rdg-border)] p-3">
+        <div className="rdg-user-card mb-2 p-3">
+          <div className="flex items-center gap-3">
+            <span className="rdg-avatar text-xs">{adminInitials(admin?.email)}</span>
+            <span className="min-w-0">
+              <span className="block truncate text-sm font-bold text-[var(--rdg-text-primary)]">{admin?.email}</span>
+              <span className="block truncate text-xs text-[var(--rdg-text-secondary)]">{admin?.role.replaceAll('_', ' ')}</span>
+            </span>
+          </div>
+        </div>
+        <button
+          onClick={handleLogout}
+          className="rdg-nav-item flex w-full items-center gap-3 px-3 py-2.5 text-sm font-semibold hover:!border-red-200 hover:!bg-red-50 hover:!text-red-700 dark:hover:!border-red-900 dark:hover:!bg-red-950/30 dark:hover:!text-red-200"
+        >
+          <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.7} aria-hidden="true">
+            <path strokeLinecap="round" strokeLinejoin="round" d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1" />
+          </svg>
+          {dict.logout}
+        </button>
+        <div className="mt-3 flex items-center gap-2 border-t border-[var(--rdg-border)] pt-3">
+          <AdminLanguageSwitcher />
+          <AdminThemeSwitcher />
+        </div>
+      </div>
+    </>
+  )
+
+  return (
+    <AdminSessionProvider admin={admin as AdminSessionUser}>
+      <div className="rdg-app-shell flex min-h-screen text-[var(--rdg-text-primary)]">
+        {navigationOpen ? (
+          <button
+            type="button"
+            className="fixed inset-0 z-40 bg-[var(--rdg-overlay)] backdrop-blur-sm lg:hidden"
+            onClick={() => setNavigationOpen(false)}
+            aria-label="Close navigation"
+          />
+        ) : null}
+
+        <aside
+          className={`rdg-sidebar fixed inset-y-0 z-50 flex w-[var(--rdg-sidebar-size)] flex-col border-e border-[var(--rdg-border)] transition-transform duration-200 lg:static lg:z-auto lg:translate-x-0 [inset-inline-start:0] ${
+            navigationOpen ? 'translate-x-0' : isRtl ? 'translate-x-full' : '-translate-x-full'
+          }`}
+        >
+          <button
+            type="button"
+            className="absolute top-4 inline-flex h-11 w-11 items-center justify-center rounded-[var(--rdg-radius-sm)] border border-[var(--rdg-border)] bg-[var(--rdg-surface-primary)] text-[var(--rdg-text-primary)] lg:hidden [inset-inline-end:1rem]"
+            onClick={() => setNavigationOpen(false)}
+            aria-label="Close navigation"
+          >
+            <svg className="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+              <path strokeLinecap="round" d="M6 6l12 12M18 6L6 18" />
+            </svg>
+          </button>
+          {navigation}
+        </aside>
+
+        <div className="rdg-workspace flex min-h-screen min-w-0 flex-1 flex-col">
+          <header className="rdg-topbar px-4 sm:px-6">
+            <div className="flex min-w-0 items-center gap-3">
+              <button
+                type="button"
+                className="inline-flex h-11 w-11 flex-shrink-0 items-center justify-center rounded-[var(--rdg-radius-sm)] border border-[var(--rdg-border)] bg-[var(--rdg-surface-primary)] text-[var(--rdg-text-primary)] lg:hidden"
+                onClick={() => setNavigationOpen(true)}
+                aria-label="Open navigation"
+                aria-expanded={navigationOpen}
+              >
+                <svg className="h-5 w-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+                  <path strokeLinecap="round" d="M4 7h16M4 12h16M4 17h16" />
+                </svg>
+              </button>
+              <div className="min-w-0">
+                <p className="rdg-topbar-kicker hidden sm:block">{dict.platform}</p>
+                <h1 className="rdg-topbar-title truncate">{pageTitle}</h1>
+              </div>
+            </div>
+            <div className="flex items-center gap-3">
+              <span className="rdg-system-status hidden md:inline-flex">Operational</span>
+              <span className="rdg-avatar text-xs">{adminInitials(admin?.email)}</span>
+            </div>
+          </header>
+
+          <main className="rdg-app-main flex-1 overflow-y-auto">
+            <div className="rdg-app-content">{children}</div>
+          </main>
+        </div>
+      </div>
+    </AdminSessionProvider>
+  )
+}
@@ -0,0 +1,694 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+type EmployeeRole = 'OWNER' | 'MANAGER' | 'AGENT'
+type Plan = 'STARTER' | 'GROWTH' | 'PRO'
+type MenuItemType = 'INTERNAL_PAGE' | 'EXTERNAL_LINK' | 'PARENT_MENU' | 'SECTION_LABEL' | 'DIVIDER'
+
+type CompanyOption = {
+  id: string
+  name: string
+  subscription?: { plan?: string | null } | null
+  status: string
+}
+
+type MenuItem = {
+  id: string
+  systemKey: string | null
+  label: string
+  itemType: MenuItemType
+  routeOrUrl: string | null
+  icon: string | null
+  parentId: string | null
+  displayOrder: number
+  openInNewTab: boolean
+  isRequired: boolean
+  isActive: boolean
+  parent?: { id: string; label: string } | null
+  roleVisibilities: Array<{ role: EmployeeRole }>
+  subscriptionAssignments: Array<{ plan: Plan; displayOrder: number; isActive: boolean }>
+  companyAssignments: Array<{
+    companyId: string
+    displayOrder: number
+    isActive: boolean
+    company: { id: string; name: string }
+  }>
+}
+
+type AuditLog = {
+  id: string
+  action: string
+  resource: string
+  resourceId: string | null
+  createdAt: string
+  adminUser: { firstName: string; lastName: string; email: string } | null
+}
+
+type PreviewItem = {
+  id: string
+  label: string
+  systemKey: string | null
+  itemType: MenuItemType
+  routeOrUrl: string | null
+  displayOrder: number
+  visible: boolean
+  source: 'subscription' | 'company' | 'none'
+  reasons: string[]
+}
+
+type PreviewResponse = {
+  company: { id: string; name: string; status: string; subscription: { plan: Plan; status: string } | null }
+  role: EmployeeRole
+  subscriptionPlan: Plan | null
+  items: PreviewItem[]
+}
+
+type FormState = {
+  label: string
+  systemKey: string
+  itemType: MenuItemType
+  routeOrUrl: string
+  icon: string
+  parentId: string
+  displayOrder: string
+  openInNewTab: boolean
+  isRequired: boolean
+  isActive: boolean
+  roles: EmployeeRole[]
+  plans: Plan[]
+  companyIds: string[]
+}
+
+const ROLES: EmployeeRole[] = ['OWNER', 'MANAGER', 'AGENT']
+const PLANS: Plan[] = ['STARTER', 'GROWTH', 'PRO']
+const ITEM_TYPES: MenuItemType[] = ['INTERNAL_PAGE', 'EXTERNAL_LINK', 'PARENT_MENU', 'SECTION_LABEL', 'DIVIDER']
+
+const INPUT = 'field mt-1'
+const LABEL = 'text-xs font-medium uppercase tracking-wider text-zinc-500'
+
+async function api<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${ADMIN_API_BASE}${path}`, {
+    ...options,
+    credentials: 'include',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(options?.headers ?? {}),
+    },
+  })
+
+  const json = await res.json()
+  if (!res.ok) throw new Error(json?.message ?? 'Request failed')
+  return (json?.data ?? json) as T
+}
+
+function emptyForm(): FormState {
+  return {
+    label: '',
+    systemKey: '',
+    itemType: 'INTERNAL_PAGE',
+    routeOrUrl: '',
+    icon: '',
+    parentId: '',
+    displayOrder: '0',
+    openInNewTab: false,
+    isRequired: false,
+    isActive: true,
+    roles: ['OWNER', 'MANAGER', 'AGENT'],
+    plans: ['STARTER', 'GROWTH', 'PRO'],
+    companyIds: [],
+  }
+}
+
+function formFromItem(item: MenuItem): FormState {
+  return {
+    label: item.label,
+    systemKey: item.systemKey ?? '',
+    itemType: item.itemType,
+    routeOrUrl: item.routeOrUrl ?? '',
+    icon: item.icon ?? '',
+    parentId: item.parentId ?? '',
+    displayOrder: String(item.displayOrder),
+    openInNewTab: item.openInNewTab,
+    isRequired: item.isRequired,
+    isActive: item.isActive,
+    roles: item.roleVisibilities.map((entry) => entry.role),
+    plans: item.subscriptionAssignments.map((entry) => entry.plan),
+    companyIds: item.companyAssignments.map((entry) => entry.companyId),
+  }
+}
+
+function chip(text: string, tone = 'default') {
+  const toneClass =
+    tone === 'success'
+      ? 'bg-emerald-950/40 text-emerald-400'
+      : tone === 'warn'
+        ? 'bg-orange-950/40 text-orange-400'
+        : 'bg-zinc-800 text-zinc-300'
+
+  return (
+    <span className={`inline-flex rounded-full px-2.5 py-1 text-[11px] font-medium ${toneClass}`}>
+      {text}
+    </span>
+  )
+}
+
+export default function MenuManagementPage() {
+  const [items, setItems] = useState<MenuItem[]>([])
+  const [companies, setCompanies] = useState<CompanyOption[]>([])
+  const [auditLogs, setAuditLogs] = useState<AuditLog[]>([])
+  const [preview, setPreview] = useState<PreviewResponse | null>(null)
+  const [previewCompanyId, setPreviewCompanyId] = useState('')
+  const [previewRole, setPreviewRole] = useState<EmployeeRole>('OWNER')
+  const [editingId, setEditingId] = useState<string | null>(null)
+  const [form, setForm] = useState<FormState>(emptyForm())
+  const [loading, setLoading] = useState(true)
+  const [saving, setSaving] = useState(false)
+  const [previewing, setPreviewing] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [success, setSuccess] = useState<string | null>(null)
+
+  const parentOptions = useMemo(
+    () => items.filter((item) => item.itemType === 'PARENT_MENU' && item.id !== editingId),
+    [items, editingId],
+  )
+
+  useEffect(() => {
+    async function load() {
+      try {
+        setLoading(true)
+        setError(null)
+        const [menuItems, companiesPage, auditPage] = await Promise.all([
+          api<MenuItem[]>('/admin/menu-items'),
+          api<{ data: CompanyOption[] }>('/admin/companies?page=1&pageSize=100'),
+          api<{ data: AuditLog[] }>('/admin/menu-audit-logs?page=1&pageSize=20'),
+        ])
+        setItems(menuItems)
+        setCompanies(companiesPage.data)
+        setAuditLogs(auditPage.data)
+        if (!previewCompanyId && companiesPage.data[0]?.id) {
+          setPreviewCompanyId(companiesPage.data[0].id)
+        }
+      } catch (err: any) {
+        setError(err.message ?? 'Failed to load menu management data.')
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    load()
+  }, [])
+
+  function updateForm<K extends keyof FormState>(key: K, value: FormState[K]) {
+    setForm((prev) => ({ ...prev, [key]: value }))
+  }
+
+  function toggleArrayValue<K extends 'roles' | 'plans' | 'companyIds'>(key: K, value: FormState[K][number]) {
+    setForm((prev) => {
+      const values = prev[key] as string[]
+      return {
+        ...prev,
+        [key]: values.includes(value as string)
+          ? values.filter((entry) => entry !== value)
+          : [...values, value as string],
+      }
+    })
+  }
+
+  async function refreshLists() {
+    const [menuItems, auditPage] = await Promise.all([
+      api<MenuItem[]>('/admin/menu-items'),
+      api<{ data: AuditLog[] }>('/admin/menu-audit-logs?page=1&pageSize=20'),
+    ])
+    setItems(menuItems)
+    setAuditLogs(auditPage.data)
+  }
+
+  async function submitForm(event: React.FormEvent) {
+    event.preventDefault()
+    try {
+      setSaving(true)
+      setError(null)
+      setSuccess(null)
+
+      const payload = {
+        label: form.label,
+        systemKey: form.systemKey || null,
+        itemType: form.itemType,
+        routeOrUrl: form.routeOrUrl || null,
+        icon: form.icon || null,
+        parentId: form.parentId || null,
+        displayOrder: Number(form.displayOrder || 0),
+        openInNewTab: form.openInNewTab,
+        isRequired: form.isRequired,
+        isActive: form.isActive,
+        roles: form.roles,
+        subscriptionPlans: form.plans.map((plan) => ({
+          plan,
+          displayOrder: Number(form.displayOrder || 0),
+          isActive: true,
+        })),
+        companyAssignments: form.companyIds.map((companyId) => ({
+          companyId,
+          displayOrder: Number(form.displayOrder || 0),
+          isActive: true,
+        })),
+      }
+
+      if (editingId) {
+        await api(`/admin/menu-items/${editingId}`, {
+          method: 'PUT',
+          body: JSON.stringify(payload),
+        })
+        setSuccess('Menu item updated.')
+      } else {
+        await api('/admin/menu-items', {
+          method: 'POST',
+          body: JSON.stringify(payload),
+        })
+        setSuccess('Menu item created.')
+      }
+
+      setEditingId(null)
+      setForm(emptyForm())
+      await refreshLists()
+    } catch (err: any) {
+      setError(err.message ?? 'Failed to save menu item.')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  function startCreate() {
+    setEditingId(null)
+    setForm(emptyForm())
+    setSuccess(null)
+    setError(null)
+  }
+
+  function startEdit(item: MenuItem) {
+    setEditingId(item.id)
+    setForm(formFromItem(item))
+    setSuccess(null)
+    setError(null)
+  }
+
+  async function toggleStatus(item: MenuItem) {
+    try {
+      setError(null)
+      await api(`/admin/menu-items/${item.id}/status`, {
+        method: 'PATCH',
+        body: JSON.stringify({ isActive: !item.isActive }),
+      })
+      await refreshLists()
+    } catch (err: any) {
+      setError(err.message ?? 'Failed to update status.')
+    }
+  }
+
+  async function removeItem(item: MenuItem) {
+    if (!window.confirm(`Delete "${item.label}"?`)) return
+    try {
+      setError(null)
+      await api(`/admin/menu-items/${item.id}`, { method: 'DELETE' })
+      if (editingId === item.id) {
+        setEditingId(null)
+        setForm(emptyForm())
+      }
+      await refreshLists()
+    } catch (err: any) {
+      setError(err.message ?? 'Failed to delete menu item.')
+    }
+  }
+
+  async function runPreview() {
+    if (!previewCompanyId) return
+    try {
+      setPreviewing(true)
+      setError(null)
+      const result = await api<PreviewResponse>('/admin/menu-preview', {
+        method: 'POST',
+        body: JSON.stringify({ companyId: previewCompanyId, role: previewRole }),
+      })
+      setPreview(result)
+    } catch (err: any) {
+      setError(err.message ?? 'Failed to load menu preview.')
+    } finally {
+      setPreviewing(false)
+    }
+  }
+
+  if (loading) {
+    return (
+      <div className="space-y-6">
+        <div className="panel p-8 text-sm text-zinc-500">
+          Loading menu management…
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      <section className="rdg-page-hero">
+        <div className="flex flex-wrap items-start justify-between gap-4">
+          <div>
+            <p className="rdg-page-kicker">Platform</p>
+            <h1 className="mt-1 text-3xl font-black">Menu Management</h1>
+            <p className="mt-1 max-w-3xl text-sm text-zinc-400">
+              Control company dashboard navigation by plan, role, and company-specific exceptions from one admin surface.
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={startCreate}
+            className="btn-primary"
+          >
+            Create menu item
+          </button>
+        </div>
+      </section>
+
+      {(error || success) && (
+        <section className="space-y-3">
+          {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+          {success && <div className="panel p-4 text-sm text-emerald-400">{success}</div>}
+        </section>
+      )}
+
+      <div className="grid gap-8 xl:grid-cols-[1.4fr,0.95fr]">
+        <section className="panel overflow-hidden">
+          <div className="flex items-center justify-between">
+            <div>
+              <h2 className="px-5 pt-5 text-xl font-semibold text-zinc-100">Menu items</h2>
+              <p className="px-5 pb-1 pt-1 text-sm text-zinc-400">{items.length} configured items</p>
+            </div>
+          </div>
+
+          <div className="overflow-x-auto">
+            <table className="min-w-full text-left text-sm">
+              <thead>
+                <tr className="border-b border-zinc-800">
+                  <th className="px-5 py-3 text-xs font-medium uppercase tracking-wider text-zinc-500">Item</th>
+                  <th className="px-5 py-3 text-xs font-medium uppercase tracking-wider text-zinc-500">Type</th>
+                  <th className="px-5 py-3 text-xs font-medium uppercase tracking-wider text-zinc-500">Assignments</th>
+                  <th className="px-5 py-3 text-xs font-medium uppercase tracking-wider text-zinc-500">Status</th>
+                  <th className="px-5 py-3 text-xs font-medium uppercase tracking-wider text-zinc-500">Actions</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-zinc-800/60">
+                {items.map((item) => (
+                  <tr key={item.id} className="align-top transition-colors hover:bg-zinc-800/30">
+                    <td className="px-5 py-4">
+                      <div className="space-y-1">
+                        <div className="flex flex-wrap items-center gap-2">
+                          <span className="font-semibold text-zinc-100">{item.label}</span>
+                          {item.isRequired && chip('Required', 'warn')}
+                          {item.systemKey && chip(item.systemKey)}
+                        </div>
+                        <p className="text-xs text-zinc-500">
+                          {item.routeOrUrl || 'No route'} • order {item.displayOrder}
+                          {item.parent ? ` • child of ${item.parent.label}` : ''}
+                        </p>
+                      </div>
+                    </td>
+                    <td className="px-5 py-4 text-xs text-zinc-300">{item.itemType}</td>
+                    <td className="px-5 py-4">
+                      <div className="space-y-2">
+                        <div className="flex flex-wrap gap-2">
+                          {item.subscriptionAssignments.length > 0
+                            ? item.subscriptionAssignments.map((assignment) => (
+                                <span key={`${item.id}-${assignment.plan}`} className="inline-flex rounded-full bg-zinc-800 px-2.5 py-1 text-[11px] font-medium text-zinc-300">
+                                  {assignment.plan}
+                                </span>
+                              ))
+                            : <span className="text-xs text-zinc-500">No plan assignments</span>}
+                        </div>
+                        <div className="flex flex-wrap gap-2">
+                          {item.companyAssignments.slice(0, 3).map((assignment) => (
+                            <span key={`${item.id}-${assignment.companyId}`} className="inline-flex rounded-full bg-zinc-800 px-2.5 py-1 text-[11px] font-medium text-zinc-300">
+                              {assignment.company.name}
+                            </span>
+                          ))}
+                          {item.companyAssignments.length > 3 && chip(`+${item.companyAssignments.length - 3} more`)}
+                        </div>
+                        <div className="flex flex-wrap gap-2">
+                          {item.roleVisibilities.map((entry) => (
+                            <span key={`${item.id}-${entry.role}`} className="inline-flex rounded-full bg-zinc-800 px-2.5 py-1 text-[11px] font-medium text-zinc-300">
+                              {entry.role}
+                            </span>
+                          ))}
+                        </div>
+                      </div>
+                    </td>
+                    <td className="px-5 py-4">
+                      {item.isActive ? chip('Active', 'success') : chip('Inactive')}
+                    </td>
+                    <td className="px-5 py-4">
+                      <div className="flex flex-wrap gap-2">
+                        <button type="button" onClick={() => startEdit(item)} className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 transition-colors hover:bg-zinc-700">
+                          Edit
+                        </button>
+                        <button type="button" onClick={() => toggleStatus(item)} className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 transition-colors hover:bg-zinc-700">
+                          {item.isActive ? 'Disable' : 'Enable'}
+                        </button>
+                        <button type="button" onClick={() => removeItem(item)} className="rounded-lg border border-red-900/60 bg-red-950/20 px-3 py-1.5 text-xs text-red-300 transition-colors hover:bg-red-900/30">
+                          Delete
+                        </button>
+                      </div>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </section>
+
+        <section className="panel p-6">
+          <div className="flex items-center justify-between gap-4">
+            <div>
+              <h2 className="text-xl font-semibold text-zinc-100">{editingId ? 'Edit menu item' : 'New menu item'}</h2>
+              <p className="mt-1 text-sm text-zinc-400">
+                Configure menu metadata, role visibility, plan defaults, and company-specific overrides.
+              </p>
+            </div>
+            {editingId && (
+              <button type="button" onClick={startCreate} className="text-sm font-medium text-orange-400 hover:text-orange-300">
+                Clear
+              </button>
+            )}
+          </div>
+
+          <form className="mt-6 space-y-5" onSubmit={submitForm}>
+            <div className="grid gap-4 sm:grid-cols-2">
+              <label>
+                <span className={LABEL}>Label</span>
+                <input className={INPUT} value={form.label} onChange={(e) => updateForm('label', e.target.value)} />
+              </label>
+
+              <label>
+                <span className={LABEL}>System key</span>
+                <input className={INPUT} value={form.systemKey} onChange={(e) => updateForm('systemKey', e.target.value)} placeholder="dashboard" />
+              </label>
+            </div>
+
+            <div className="grid gap-4 sm:grid-cols-2">
+              <label>
+                <span className={LABEL}>Type</span>
+                <select className={INPUT} value={form.itemType} onChange={(e) => updateForm('itemType', e.target.value as MenuItemType)}>
+                  {ITEM_TYPES.map((type) => <option key={type} value={type}>{type}</option>)}
+                </select>
+              </label>
+
+              <label>
+                <span className={LABEL}>Icon</span>
+                <input className={INPUT} value={form.icon} onChange={(e) => updateForm('icon', e.target.value)} placeholder="LayoutDashboard" />
+              </label>
+            </div>
+
+            <div className="grid gap-4 sm:grid-cols-2">
+              <label>
+                <span className={LABEL}>Route or URL</span>
+                <input className={INPUT} value={form.routeOrUrl} onChange={(e) => updateForm('routeOrUrl', e.target.value)} placeholder="/reports or https://…" />
+              </label>
+
+              <label>
+                <span className={LABEL}>Parent menu</span>
+                <select className={INPUT} value={form.parentId} onChange={(e) => updateForm('parentId', e.target.value)}>
+                  <option value="">No parent</option>
+                  {parentOptions.map((item) => (
+                    <option key={item.id} value={item.id}>{item.label}</option>
+                  ))}
+                </select>
+              </label>
+            </div>
+
+            <div className="grid gap-4 sm:grid-cols-2">
+              <label>
+                <span className={LABEL}>Display order</span>
+                <input className={INPUT} type="number" min="0" value={form.displayOrder} onChange={(e) => updateForm('displayOrder', e.target.value)} />
+              </label>
+
+              <div className="grid gap-3 sm:grid-cols-2">
+                <label className="flex items-center gap-2 rounded-xl border border-zinc-700 bg-zinc-900/40 px-3 py-2 text-sm text-zinc-200">
+                  <input type="checkbox" checked={form.isActive} onChange={(e) => updateForm('isActive', e.target.checked)} />
+                  Active
+                </label>
+                <label className="flex items-center gap-2 rounded-xl border border-zinc-700 bg-zinc-900/40 px-3 py-2 text-sm text-zinc-200">
+                  <input type="checkbox" checked={form.openInNewTab} onChange={(e) => updateForm('openInNewTab', e.target.checked)} />
+                  New tab
+                </label>
+              </div>
+            </div>
+
+            <label className="flex items-center gap-2 rounded-xl border border-zinc-700 bg-zinc-900/40 px-3 py-2 text-sm text-zinc-200">
+              <input type="checkbox" checked={form.isRequired} onChange={(e) => updateForm('isRequired', e.target.checked)} />
+              Required system item
+            </label>
+
+            <div>
+              <p className={LABEL}>Role visibility</p>
+              <div className="mt-2 flex flex-wrap gap-2">
+                {ROLES.map((role) => (
+                  <label key={role} className="flex items-center gap-2 rounded-full border border-zinc-700 bg-zinc-900/40 px-3 py-2 text-sm text-zinc-200">
+                    <input type="checkbox" checked={form.roles.includes(role)} onChange={() => toggleArrayValue('roles', role)} />
+                    {role}
+                  </label>
+                ))}
+              </div>
+            </div>
+
+            <div>
+              <p className={LABEL}>Subscription plans</p>
+              <div className="mt-2 flex flex-wrap gap-2">
+                {PLANS.map((plan) => (
+                  <label key={plan} className="flex items-center gap-2 rounded-full border border-zinc-700 bg-zinc-900/40 px-3 py-2 text-sm text-zinc-200">
+                    <input type="checkbox" checked={form.plans.includes(plan)} onChange={() => toggleArrayValue('plans', plan)} />
+                    {plan}
+                  </label>
+                ))}
+              </div>
+            </div>
+
+            <div>
+              <p className={LABEL}>Company-specific assignments</p>
+              <div className="mt-2 max-h-56 space-y-2 overflow-y-auto rounded-2xl border border-zinc-700 bg-zinc-900/30 p-3">
+                {companies.map((company) => (
+                  <label key={company.id} className="flex items-center justify-between gap-3 rounded-xl px-2 py-2 text-sm text-zinc-200 transition-colors hover:bg-zinc-800/40">
+                    <span className="flex items-center gap-2">
+                      <input type="checkbox" checked={form.companyIds.includes(company.id)} onChange={() => toggleArrayValue('companyIds', company.id)} />
+                      <span>{company.name}</span>
+                    </span>
+                    <span className="text-xs text-zinc-500">
+                      {company.subscription?.plan ?? 'No plan'} • {company.status}
+                    </span>
+                  </label>
+                ))}
+              </div>
+            </div>
+
+            <button
+              type="submit"
+              disabled={saving}
+              className="btn-primary w-full"
+            >
+              {saving ? 'Saving…' : editingId ? 'Update menu item' : 'Create menu item'}
+            </button>
+          </form>
+        </section>
+      </div>
+
+      <div className="grid gap-8 xl:grid-cols-[1.1fr,0.9fr]">
+        <section className="panel p-6">
+          <div className="flex flex-wrap items-end gap-4">
+            <div className="flex-1">
+              <h2 className="text-xl font-semibold text-zinc-100">Preview company menu</h2>
+              <p className="mt-1 text-sm text-zinc-400">
+                Test the generated menu for a company and role before troubleshooting or saving follow-up changes.
+              </p>
+            </div>
+            <div className="min-w-[220px]">
+              <label className={LABEL}>Company</label>
+              <select className={INPUT} value={previewCompanyId} onChange={(e) => setPreviewCompanyId(e.target.value)}>
+                {companies.map((company) => (
+                  <option key={company.id} value={company.id}>{company.name}</option>
+                ))}
+              </select>
+            </div>
+            <div className="min-w-[160px]">
+              <label className={LABEL}>Role</label>
+              <select className={INPUT} value={previewRole} onChange={(e) => setPreviewRole(e.target.value as EmployeeRole)}>
+                {ROLES.map((role) => <option key={role} value={role}>{role}</option>)}
+              </select>
+            </div>
+            <button
+              type="button"
+              onClick={runPreview}
+              disabled={previewing || !previewCompanyId}
+              className="btn-primary"
+            >
+              {previewing ? 'Previewing…' : 'Run preview'}
+            </button>
+          </div>
+
+          {preview && (
+            <div className="mt-6 space-y-4">
+              <div className="rounded-2xl border border-zinc-700 bg-zinc-900/30 p-4">
+                <p className="text-sm font-semibold text-zinc-100">{preview.company.name}</p>
+                <p className="mt-1 text-xs text-zinc-500">
+                  Plan: {preview.subscriptionPlan ?? 'None'} • Role: {preview.role} • Company status: {preview.company.status}
+                </p>
+              </div>
+
+              <div className="space-y-3">
+                {preview.items.map((item) => (
+                  <div key={item.id} className="rounded-2xl border border-zinc-700 bg-zinc-900/30 p-4">
+                    <div className="flex flex-wrap items-center gap-2">
+                      <span className="font-semibold text-zinc-100">{item.label}</span>
+                      {item.visible ? chip('Visible', 'success') : chip('Hidden')}
+                      {chip(item.source === 'none' ? 'unassigned' : item.source)}
+                    </div>
+                    <p className="mt-1 text-xs text-zinc-500">
+                      {item.routeOrUrl || 'No route'} • order {item.displayOrder}
+                    </p>
+                    <ul className="mt-3 space-y-1 text-sm text-zinc-300">
+                      {item.reasons.map((reason, index) => (
+                        <li key={`${item.id}-${index}`}>{reason}</li>
+                      ))}
+                    </ul>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+        </section>
+
+        <section className="panel p-6">
+          <h2 className="text-xl font-semibold text-zinc-100">Recent menu audit activity</h2>
+          <p className="mt-1 text-sm text-zinc-400">
+            Recent platform-side changes to menu items and assignments.
+          </p>
+
+          <div className="mt-6 space-y-3">
+            {auditLogs.map((entry) => (
+              <div key={entry.id} className="rounded-2xl border border-zinc-700 bg-zinc-900/30 p-4">
+                <div className="flex items-center justify-between gap-3">
+                  <p className="text-sm font-semibold text-zinc-100">{entry.action}</p>
+                  <span className="text-xs text-zinc-500">
+                    {new Date(entry.createdAt).toLocaleString()}
+                  </span>
+                </div>
+                <p className="mt-1 text-xs text-zinc-500">
+                  {entry.adminUser
+                    ? `${entry.adminUser.firstName} ${entry.adminUser.lastName} • ${entry.adminUser.email}`
+                    : 'Unknown admin'}
+                </p>
+              </div>
+            ))}
+          </div>
+        </section>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,205 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface NotificationItem {
+  id: string
+  type: string
+  title: string
+  body: string
+  channel: string
+  status: string
+  locale: string
+  sentAt: string | null
+  createdAt: string
+  company: { name: string } | null
+  companyId: string | null
+  renterId: string | null
+}
+
+interface Paginated {
+  data: NotificationItem[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+const CHANNELS = ['EMAIL', 'SMS', 'WHATSAPP', 'IN_APP', 'PUSH']
+const STATUSES = ['PENDING', 'SENT', 'DELIVERED', 'FAILED', 'READ']
+
+const CHANNEL_BADGE: Record<string, string> = {
+  EMAIL:    'text-sky-400 bg-sky-950/40',
+  SMS:      'text-emerald-400 bg-emerald-950/40',
+  WHATSAPP: 'text-teal-400 bg-teal-950/40',
+  IN_APP:   'text-violet-400 bg-violet-950/40',
+  PUSH:     'text-orange-400 bg-orange-950/40',
+}
+
+const STATUS_BADGE: Record<string, string> = {
+  PENDING:   'text-yellow-400 bg-yellow-950/40',
+  SENT:      'text-emerald-400 bg-emerald-950/40',
+  DELIVERED: 'text-emerald-400 bg-emerald-950/40',
+  FAILED:    'text-red-400 bg-red-950/40',
+  READ:      'text-zinc-400 bg-zinc-800',
+}
+
+export default function AdminNotificationsPage() {
+  const [result, setResult] = useState<Paginated | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [filterChannel, setFilterChannel] = useState('')
+  const [filterStatus, setFilterStatus] = useState('')
+  const [filterCompany, setFilterCompany] = useState('')
+  const [page, setPage] = useState(1)
+
+  function load(p: number) {
+    setLoading(true)
+    setError(null)
+    const params = new URLSearchParams({ page: String(p), pageSize: '50' })
+    if (filterChannel) params.set('channel', filterChannel)
+    if (filterStatus)  params.set('status',  filterStatus)
+    if (filterCompany) params.set('companyId', filterCompany)
+
+    fetch(`${ADMIN_API_BASE}/admin/notifications?${params.toString()}`, {
+      credentials: 'include',
+      cache: 'no-store',
+    })
+      .then((r) => r.json())
+      .then((json) => setResult(json.data ?? null))
+      .catch((err) => setError(err.message))
+      .finally(() => setLoading(false))
+  }
+
+  useEffect(() => {
+    setPage(1)
+    load(1)
+  }, [filterChannel, filterStatus, filterCompany])
+
+  function goToPage(p: number) {
+    setPage(p)
+    load(p)
+  }
+
+  const totalPages = result ? Math.ceil(result.total / result.pageSize) : 0
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex flex-wrap items-start justify-between gap-4">
+        <div>
+          <p className="rdg-page-kicker">Platform</p>
+          <h1 className="mt-1 text-3xl font-black">Notifications</h1>
+          <p className="mt-1 text-sm text-zinc-400">
+            Full audit log of every notification sent across all companies.
+          </p>
+        </div>
+        {result && (
+          <span className="rounded-full bg-zinc-800 px-3 py-1 text-sm text-zinc-300">
+            {result.total.toLocaleString()} total
+          </span>
+        )}
+      </div>
+
+      {/* Filters */}
+      <div className="flex flex-wrap items-center gap-3">
+        <select
+          value={filterChannel}
+          onChange={(e) => setFilterChannel(e.target.value)}
+          className="rounded-xl border border-zinc-700 bg-zinc-800 px-3 py-2 text-sm text-zinc-100 focus:outline-none focus:ring-2 focus:ring-orange-500"
+        >
+          <option value="">All channels</option>
+          {CHANNELS.map((ch) => <option key={ch} value={ch}>{ch}</option>)}
+        </select>
+        <select
+          value={filterStatus}
+          onChange={(e) => setFilterStatus(e.target.value)}
+          className="rounded-xl border border-zinc-700 bg-zinc-800 px-3 py-2 text-sm text-zinc-100 focus:outline-none focus:ring-2 focus:ring-orange-500"
+        >
+          <option value="">All statuses</option>
+          {STATUSES.map((s) => <option key={s} value={s}>{s}</option>)}
+        </select>
+      </div>
+
+      {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+
+      <div className="panel overflow-hidden">
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800">
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Date</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Company</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Event</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Channel</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Title</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Status</th>
+                <th className="px-5 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">Sent at</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr><td colSpan={7} className="px-5 py-12 text-center text-zinc-500">Loading…</td></tr>
+              ) : !result || result.data.length === 0 ? (
+                <tr><td colSpan={7} className="px-5 py-12 text-center text-zinc-500">No notifications found.</td></tr>
+              ) : result.data.map((item) => (
+                <tr key={item.id} className="hover:bg-zinc-800/30 transition-colors">
+                  <td className="whitespace-nowrap px-5 py-3 text-xs text-zinc-500">
+                    {new Date(item.createdAt).toLocaleString()}
+                  </td>
+                  <td className="whitespace-nowrap px-5 py-3 text-xs text-zinc-300">
+                    {item.company?.name ?? (item.companyId ? item.companyId.slice(0, 10) + '…' : '—')}
+                  </td>
+                  <td className="whitespace-nowrap px-5 py-3 text-xs font-medium text-zinc-300">
+                    {item.type.replaceAll('_', ' ')}
+                  </td>
+                  <td className="px-5 py-3">
+                    <span className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${CHANNEL_BADGE[item.channel] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {item.channel}
+                    </span>
+                  </td>
+                  <td className="px-5 py-3 max-w-[220px]">
+                    <p className="truncate text-sm text-zinc-200">{item.title}</p>
+                    <p className="truncate text-xs text-zinc-500">{item.body}</p>
+                  </td>
+                  <td className="px-5 py-3">
+                    <span className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${STATUS_BADGE[item.status] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {item.status}
+                    </span>
+                  </td>
+                  <td className="whitespace-nowrap px-5 py-3 text-xs text-zinc-500">
+                    {item.sentAt ? new Date(item.sentAt).toLocaleString() : '—'}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+
+        {/* Pagination */}
+        {totalPages > 1 && (
+          <div className="flex items-center justify-between border-t border-zinc-800 px-5 py-3">
+            <span className="text-xs text-zinc-500">
+              Page {page} of {totalPages} — {result?.total.toLocaleString()} records
+            </span>
+            <div className="flex items-center gap-2">
+              <button
+                disabled={page <= 1}
+                onClick={() => goToPage(page - 1)}
+                className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 transition-colors hover:bg-zinc-700 disabled:cursor-not-allowed disabled:opacity-40"
+              >
+                Previous
+              </button>
+              <button
+                disabled={page >= totalPages}
+                onClick={() => goToPage(page + 1)}
+                className="rounded-lg border border-zinc-700 bg-zinc-800 px-3 py-1.5 text-xs text-zinc-300 transition-colors hover:bg-zinc-700 disabled:cursor-not-allowed disabled:opacity-40"
+              >
+                Next
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,245 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import Link from 'next/link'
+import { Activity, ArrowRight, Building2, ClipboardList, ShieldCheck, Users, WalletCards } from 'lucide-react'
+import { useAdminI18n } from '@/components/I18nProvider'
+import { ADMIN_API_BASE } from '@/lib/api'
+import { canAccessAdminMetrics, useAdminSession } from './AdminSessionContext'
+
+interface Metrics {
+  totalCompanies: number
+  activeCompanies: number
+  totalRenters: number
+  totalReservations: number
+  mrr?: number
+}
+
+export default function AdminDashboardPage() {
+  const { language } = useAdminI18n()
+  const admin = useAdminSession()
+  const copy = {
+    en: {
+      kpis: ['Total companies', 'Active companies', 'Total renters', 'Total reservations'],
+      brand: 'RentalDriveGo',
+      eyebrow: 'Operations command',
+      platformOverview: 'RentalDriveGo admin dashboard',
+      subtitle: 'Monitor marketplace health, subscription coverage, renter activity, and operator actions from one control surface.',
+      liveSignal: 'Live platform signal',
+      readiness: 'Operational readiness',
+      readinessBody: 'Core admin workflows are connected and ready for platform support.',
+      quickActions: 'Quick actions',
+      mrr: 'Monthly recurring revenue',
+      noMetrics: 'Metrics are limited for this admin role.',
+      cards: [
+        ['Companies', 'Search operators, review subscription state, and manage account status.', 'View all'],
+        ['Renters', 'Support renter trust workflows, blocking, and account recovery.', 'View all'],
+        ['Audit logs', 'Trace every sensitive admin action across RentalDriveGo.', 'View logs'],
+      ],
+      health: ['Tenant accounts', 'Marketplace identity', 'Admin audit trail'],
+    },
+    fr: {
+      kpis: ['Entreprises totales', 'Entreprises actives', 'Locataires totaux', 'Réservations totales'],
+      brand: 'RentalDriveGo',
+      eyebrow: 'Centre des opérations',
+      platformOverview: 'Tableau de bord admin RentalDriveGo',
+      subtitle: 'Suivez la santé de la marketplace, les abonnements, l’activité des locataires et les actions opérateur depuis une même interface.',
+      liveSignal: 'Signal plateforme en direct',
+      readiness: 'Disponibilité opérationnelle',
+      readinessBody: 'Les principaux workflows admin sont connectés et prêts pour le support plateforme.',
+      quickActions: 'Actions rapides',
+      mrr: 'Revenu mensuel récurrent',
+      noMetrics: 'Les métriques sont limitées pour ce rôle admin.',
+      cards: [
+        ['Entreprises', 'Rechercher les opérateurs, vérifier les abonnements et gérer les statuts.', 'Voir tout'],
+        ['Locataires', 'Gérer les workflows de confiance, de blocage et de récupération.', 'Voir tout'],
+        ['Journaux d’audit', 'Tracer chaque action admin sensible dans RentalDriveGo.', 'Voir les journaux'],
+      ],
+      health: ['Comptes locataires', 'Identité marketplace', 'Piste d’audit admin'],
+    },
+    ar: {
+      kpis: ['إجمالي الشركات', 'الشركات النشطة', 'إجمالي المستأجرين', 'إجمالي الحجوزات'],
+      brand: 'RentalDriveGo',
+      eyebrow: 'مركز العمليات',
+      platformOverview: 'لوحة إدارة RentalDriveGo',
+      subtitle: 'راقب صحة السوق وحالة الاشتراكات ونشاط المستأجرين وإجراءات الإدارة من مساحة واحدة.',
+      liveSignal: 'مؤشر المنصة المباشر',
+      readiness: 'جاهزية التشغيل',
+      readinessBody: 'مسارات الإدارة الأساسية متصلة وجاهزة لدعم المنصة.',
+      quickActions: 'إجراءات سريعة',
+      mrr: 'الإيراد الشهري المتكرر',
+      noMetrics: 'المؤشرات محدودة لهذا الدور الإداري.',
+      cards: [
+        ['الشركات', 'ابحث عن المشغلين وراجع الاشتراكات وأدر حالة الحساب.', 'عرض الكل'],
+        ['المستأجرون', 'إدارة الثقة والحظر واستعادة الحسابات للمستأجرين.', 'عرض الكل'],
+        ['سجلات التدقيق', 'تتبع كل إجراء إداري حساس داخل RentalDriveGo.', 'عرض السجلات'],
+      ],
+      health: ['حسابات الشركات', 'هوية السوق', 'سجل تدقيق الإدارة'],
+    },
+  }[language]
+  const [metrics, setMetrics] = useState<Metrics | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    if (!canAccessAdminMetrics(admin)) {
+      setMetrics(null)
+      setLoading(false)
+      return
+    }
+
+    fetch(`${ADMIN_API_BASE}/admin/metrics`, {
+      credentials: 'include',
+      cache: 'no-store',
+    })
+      .then(async (response) => {
+        const json = await response.json().catch(() => null)
+        if (!response.ok) {
+          setMetrics(null)
+          return
+        }
+        setMetrics((json?.data ?? json) as Metrics)
+      })
+      .catch(() => null)
+      .finally(() => setLoading(false))
+  }, [admin])
+
+  const numberFormatter = new Intl.NumberFormat(language === 'ar' ? 'ar-MA' : language === 'fr' ? 'fr-FR' : 'en-US')
+  const currencyFormatter = new Intl.NumberFormat(language === 'ar' ? 'ar-MA' : language === 'fr' ? 'fr-FR' : 'en-US', {
+    style: 'currency',
+    currency: 'USD',
+    maximumFractionDigits: 0,
+  })
+
+  const kpis = metrics
+    ? [
+        { label: copy.kpis[0], value: metrics.totalCompanies, icon: Building2, tone: 'text-blue-600 dark:text-blue-300', bg: 'bg-blue-50 dark:bg-blue-500/10' },
+        { label: copy.kpis[1], value: metrics.activeCompanies, icon: Activity, tone: 'text-emerald-600 dark:text-emerald-300', bg: 'bg-emerald-50 dark:bg-emerald-500/10' },
+        { label: copy.kpis[2], value: metrics.totalRenters, icon: Users, tone: 'text-violet-600 dark:text-violet-300', bg: 'bg-violet-50 dark:bg-violet-500/10' },
+        { label: copy.kpis[3], value: metrics.totalReservations, icon: ClipboardList, tone: 'text-orange-600 dark:text-orange-300', bg: 'bg-orange-50 dark:bg-orange-500/10' },
+      ]
+    : []
+
+  const activeRate = metrics?.totalCompanies
+    ? Math.round((metrics.activeCompanies / metrics.totalCompanies) * 100)
+    : 0
+  const renterRatio = metrics?.totalCompanies
+    ? Math.round(metrics.totalRenters / Math.max(metrics.totalCompanies, 1))
+    : 0
+
+  const actionCards = [
+    { href: '/dashboard/companies', icon: Building2, title: copy.cards[0][0], body: copy.cards[0][1], cta: copy.cards[0][2] },
+    { href: '/dashboard/renters', icon: Users, title: copy.cards[1][0], body: copy.cards[1][1], cta: copy.cards[1][2] },
+    { href: '/dashboard/audit-logs', icon: ShieldCheck, title: copy.cards[2][0], body: copy.cards[2][1], cta: copy.cards[2][2] },
+  ]
+
+  return (
+    <div className="space-y-8">
+      <div className="grid gap-5 lg:grid-cols-[minmax(0,1.45fr)_minmax(320px,0.55fr)]">
+        <section className="rdg-page-hero">
+          
+          <div className="flex flex-col gap-5 md:flex-row md:items-start md:justify-between">
+            <div className="max-w-2xl">
+              <p className="rdg-page-kicker">{copy.eyebrow}</p>
+              <h1 className="mt-3 text-4xl font-black tracking-normal text-blue-950 dark:text-white sm:text-5xl">{copy.platformOverview}</h1>
+              <p className="mt-4 max-w-2xl text-sm leading-6 text-stone-600 dark:text-slate-300">{copy.subtitle}</p>
+            </div>
+            <div className="flex w-full max-w-[15rem] items-center gap-3 rounded-2xl border border-stone-200/80 bg-stone-50/90 p-3 dark:border-blue-900/60 dark:bg-[#0d1b38]/85">
+              <div className="grid h-10 w-10 place-items-center rounded-xl bg-blue-950 text-white dark:bg-orange-500">
+                <WalletCards className="h-5 w-5" aria-hidden="true" />
+              </div>
+              <div>
+                <p className="text-xs text-stone-500 dark:text-slate-400">{copy.mrr}</p>
+                <p className="text-lg font-black text-blue-950 dark:text-white">{metrics?.mrr != null ? currencyFormatter.format(metrics.mrr) : '—'}</p>
+              </div>
+            </div>
+          </div>
+          <div className="mt-8 grid gap-3 sm:grid-cols-3">
+            {copy.health.map((item) => (
+              <div key={item} className="rounded-2xl border border-stone-200/70 bg-white/70 px-4 py-3 text-sm font-semibold text-stone-700 dark:border-blue-900/50 dark:bg-[#0d1b38]/70 dark:text-slate-200">
+                {item}
+              </div>
+            ))}
+          </div>
+        </section>
+
+        <section className="panel p-6">
+          <p className="text-xs font-semibold uppercase tracking-[0.2em] text-emerald-400">{copy.liveSignal}</p>
+          <div className="mt-5 space-y-5">
+            <div>
+              <div className="flex items-center justify-between text-sm">
+                <span className="font-semibold text-zinc-200">{copy.readiness}</span>
+                <span className="font-black text-orange-600 dark:text-orange-300">{activeRate}%</span>
+              </div>
+              <div className="mt-2 h-2 overflow-hidden rounded-full bg-stone-200 dark:bg-blue-950">
+                <div className="h-full rounded-full bg-[linear-gradient(90deg,#2563eb,#f97316)]" style={{ width: `${Math.min(activeRate, 100)}%` }} />
+              </div>
+              <p className="mt-3 text-sm leading-6 text-zinc-500">{copy.readinessBody}</p>
+            </div>
+            <div className="grid grid-cols-2 gap-3">
+              <div className="rounded-2xl border border-stone-200/80 bg-stone-50/80 p-4 dark:border-blue-900/50 dark:bg-[#07101e]/70">
+                <p className="text-xs text-zinc-500">{copy.kpis[1]}</p>
+                <p className="mt-1 text-2xl font-black text-zinc-200">{metrics ? numberFormatter.format(metrics.activeCompanies) : '—'}</p>
+              </div>
+              <div className="rounded-2xl border border-stone-200/80 bg-stone-50/80 p-4 dark:border-blue-900/50 dark:bg-[#07101e]/70">
+                <p className="text-xs text-zinc-500">{copy.kpis[2]}</p>
+                <p className="mt-1 text-2xl font-black text-zinc-200">{metrics ? numberFormatter.format(renterRatio) : '—'}</p>
+              </div>
+            </div>
+          </div>
+        </section>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+        {loading
+          ? Array.from({ length: 4 }).map((_, i) => (
+              <div key={i} className="panel p-6 animate-pulse">
+                <div className="h-3 w-24 rounded bg-zinc-800" />
+                <div className="mt-3 h-8 w-16 rounded bg-zinc-800" />
+              </div>
+            ))
+          : kpis.length > 0 ? kpis.map((kpi) => {
+              const Icon = kpi.icon
+              return (
+                <div key={kpi.label} className="panel p-5">
+                  <div className="flex items-start justify-between gap-3">
+                    <div>
+                      <p className="text-xs font-medium text-zinc-500">{kpi.label}</p>
+                      <p className="mt-2 text-3xl font-black text-zinc-200">{numberFormatter.format(kpi.value ?? 0)}</p>
+                    </div>
+                    <div className={`grid h-10 w-10 place-items-center rounded-2xl ${kpi.bg}`}>
+                      <Icon className={`h-5 w-5 ${kpi.tone}`} aria-hidden="true" />
+                    </div>
+                  </div>
+                </div>
+              )
+            }) : (
+              <div className="panel p-6 md:col-span-2 lg:col-span-4">
+                <p className="text-sm text-zinc-500">{copy.noMetrics}</p>
+              </div>
+            )}
+      </div>
+
+      <section>
+        <div className="mb-4 flex items-center justify-between">
+          <p className="text-sm font-bold text-blue-950 dark:text-white">{copy.quickActions}</p>
+          <p className="text-xs font-semibold uppercase tracking-[0.18em] text-zinc-500">{copy.brand}</p>
+        </div>
+        <div className="grid gap-5 md:grid-cols-3">
+          {actionCards.map(({ href, icon: Icon, title, body, cta }) => (
+            <Link key={href} href={href} className="panel group block p-6 hover:border-orange-300 dark:hover:border-orange-500/70">
+              <div className="flex items-start justify-between gap-4">
+                <div className="grid h-11 w-11 place-items-center rounded-2xl bg-blue-950 text-white dark:bg-orange-500">
+                  <Icon className="h-5 w-5" aria-hidden="true" />
+                </div>
+                <ArrowRight className="h-4 w-4 text-zinc-500 transition-transform group-hover:translate-x-1 group-hover:text-orange-500" aria-hidden="true" />
+              </div>
+              <p className="mt-5 text-base font-bold text-zinc-200">{title}</p>
+              <p className="mt-2 min-h-[3rem] text-sm leading-6 text-zinc-500">{body}</p>
+              <p className="mt-5 text-xs font-bold uppercase tracking-[0.16em] text-emerald-400">{cta}</p>
+            </Link>
+          ))}
+        </div>
+      </section>
+    </div>
+  )
+}
@@ -0,0 +1,186 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useAdminI18n } from '@/components/I18nProvider'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface Renter {
+  id: string
+  firstName: string
+  lastName: string
+  email: string
+  phone: string | null
+  isBlocked: boolean
+  createdAt: string
+}
+
+export default function AdminRentersPage() {
+  const { language, dict } = useAdminI18n()
+  const copy = {
+    en: {
+      title: 'Renters',
+      search: 'Search renters…',
+      name: 'Name',
+      email: 'Email',
+      phone: 'Phone',
+      status: 'Status',
+      joined: 'Joined',
+      loading: 'Loading…',
+      empty: 'No renters found',
+      blocked: 'Blocked',
+      active: 'Active',
+      unblock: 'Unblock',
+      block: 'Block',
+    },
+    fr: {
+      title: 'Locataires',
+      search: 'Rechercher des locataires…',
+      name: 'Nom',
+      email: 'E-mail',
+      phone: 'Téléphone',
+      status: 'Statut',
+      joined: 'Date d’inscription',
+      loading: 'Chargement…',
+      empty: 'Aucun locataire trouvé',
+      blocked: 'Bloqué',
+      active: 'Actif',
+      unblock: 'Débloquer',
+      block: 'Bloquer',
+    },
+    ar: {
+      title: 'المستأجرون',
+      search: 'ابحث عن مستأجرين…',
+      name: 'الاسم',
+      email: 'البريد الإلكتروني',
+      phone: 'الهاتف',
+      status: 'الحالة',
+      joined: 'تاريخ التسجيل',
+      loading: 'جارٍ التحميل…',
+      empty: 'لم يتم العثور على مستأجرين',
+      blocked: 'محظور',
+      active: 'نشط',
+      unblock: 'فك الحظر',
+      block: 'حظر',
+    },
+  }[language]
+  const [renters, setRenters] = useState<Renter[]>([])
+  const [filtered, setFiltered] = useState<Renter[]>([])
+  const [search, setSearch] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [actioning, setActioning] = useState<string | null>(null)
+
+  async function fetchRenters() {
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/renters`, {
+        cache: 'no-store',
+        credentials: 'include',
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.message ?? 'Failed')
+      const list = Array.isArray(json.data) ? json.data : (json.data?.data ?? [])
+      setRenters(list)
+      setFiltered(list)
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => { fetchRenters() }, [])
+
+  useEffect(() => {
+    const q = search.toLowerCase()
+    setFiltered(renters.filter((r) =>
+      `${r.firstName} ${r.lastName}`.toLowerCase().includes(q) || r.email.toLowerCase().includes(q)
+    ))
+  }, [search, renters])
+
+  async function toggleBlock(id: string, isBlocked: boolean) {
+    setActioning(id)
+    try {
+      const endpoint = isBlocked ? 'unblock' : 'block'
+      const res = await fetch(`${ADMIN_API_BASE}/admin/renters/${id}/${endpoint}`, {
+        method: 'POST',
+        credentials: 'include',
+      })
+      if (!res.ok) throw new Error('Action failed')
+      await fetchRenters()
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setActioning(null)
+    }
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex items-center justify-between">
+        <div>
+          <p className="rdg-page-kicker">{dict.platform}</p>
+          <h1 className="mt-1 text-3xl font-black">{copy.title}</h1>
+        </div>
+        <input
+          className="w-64 px-3 py-2 rounded-xl bg-zinc-800 border border-zinc-700 text-zinc-100 text-sm placeholder:text-zinc-500 focus:outline-none focus:ring-2 focus:ring-orange-500"
+          placeholder={copy.search}
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+        />
+      </div>
+
+      {error && <div className="panel p-4 text-sm text-red-400">{error}</div>}
+
+      <div className="panel overflow-hidden">
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800">
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.name}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.email}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.phone}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.status}</th>
+                <th className="text-left px-6 py-3 text-xs font-medium text-zinc-500 uppercase tracking-wider">{copy.joined}</th>
+                <th className="px-6 py-3" />
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr><td colSpan={6} className="px-6 py-12 text-center text-zinc-500">{copy.loading}</td></tr>
+              ) : filtered.length === 0 ? (
+                <tr><td colSpan={6} className="px-6 py-12 text-center text-zinc-500">{copy.empty}</td></tr>
+              ) : filtered.map((r) => (
+                <tr key={r.id} className="hover:bg-zinc-800/30 transition-colors">
+                  <td className="px-6 py-4 font-medium text-zinc-100">{r.firstName} {r.lastName}</td>
+                  <td className="px-6 py-4 text-zinc-400">{r.email}</td>
+                  <td className="px-6 py-4 text-zinc-400">{r.phone ?? '—'}</td>
+                  <td className="px-6 py-4">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${
+                      r.isBlocked ? 'text-red-400 bg-red-950/40' : 'text-emerald-400 bg-emerald-950/40'
+                    }`}>
+                      {r.isBlocked ? copy.blocked : copy.active}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4 text-zinc-500 text-xs">{new Date(r.createdAt).toLocaleDateString()}</td>
+                  <td className="px-6 py-4">
+                    <button
+                      onClick={() => toggleBlock(r.id, r.isBlocked)}
+                      disabled={actioning === r.id}
+                      className={`px-3 py-1.5 rounded-lg text-xs font-medium transition-colors disabled:opacity-50 ${
+                        r.isBlocked
+                          ? 'bg-emerald-950/50 hover:bg-emerald-900/50 text-emerald-400'
+                          : 'bg-red-950/50 hover:bg-red-900/50 text-red-400'
+                      }`}
+                    >
+                      {r.isBlocked ? copy.unblock : copy.block}
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,799 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import Link from 'next/link'
+import {
+  cloneMarketplaceHomepageContent,
+  resolveMarketplaceHomepageSections,
+  type MarketplaceHomepageConfig,
+  type MarketplaceHomepageContent,
+  type MarketplaceHomepageSectionType,
+  type MarketplaceLanguage,
+} from '@rentaldrivego/types'
+import { useAdminI18n } from '@/components/I18nProvider'
+import { ADMIN_API_BASE } from '@/lib/api'
+
+interface Company {
+  id: string
+  name: string
+  slug: string
+  status: string
+  email: string
+  brand: {
+    displayName: string | null
+  } | null
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  ACTIVE: 'text-emerald-400 bg-emerald-900/30',
+  TRIALING: 'text-sky-400 bg-sky-900/30',
+  SUSPENDED: 'text-red-400 bg-red-900/30',
+  PENDING: 'text-orange-400 bg-orange-900/30',
+  CANCELLED: 'text-zinc-400 bg-zinc-800',
+}
+
+const INPUT_CLASS = 'w-full rounded-xl border border-zinc-700 bg-zinc-900 px-3 py-2 text-sm text-zinc-100 placeholder:text-zinc-500 focus:outline-none focus:ring-2 focus:ring-orange-500'
+const LABEL_CLASS = 'mb-2 block text-xs font-semibold uppercase tracking-[0.16em] text-zinc-500'
+
+function cloneHomepageContent(content: MarketplaceHomepageConfig) {
+  const cloned = JSON.parse(JSON.stringify(content)) as MarketplaceHomepageConfig
+  ;(['en', 'fr', 'ar'] as MarketplaceLanguage[]).forEach((language) => {
+    cloned[language].sections = resolveMarketplaceHomepageSections(cloned[language].sections)
+  })
+  return cloned
+}
+
+const HOMEPAGE_SECTIONS: MarketplaceHomepageSectionType[] = [
+  'hero',
+  'surface',
+  'pillars',
+  'audiences',
+  'features',
+  'steps',
+  'closing',
+]
+
+export default function AdminSiteConfigPage() {
+  const { language, dict } = useAdminI18n()
+  const copy = {
+    en: {
+      title: 'Site configuration',
+      description: 'Edit the main marketplace homepage here, or jump into a company to manage its branded public homepage and menu.',
+      homepageTitle: 'Main website homepage',
+      homepageDescription: 'This controls the marketplace homepage shown on the main RentalDriveGo website.',
+      saveHomepage: 'Save homepage',
+      savingHomepage: 'Saving…',
+      homepageSaved: 'Marketplace homepage saved.',
+      search: 'Search by company or slug…',
+      loading: 'Loading…',
+      empty: 'No companies found',
+      company: 'Company',
+      slug: 'Slug',
+      status: 'Status',
+      actions: 'Actions',
+      configure: 'Configure site',
+      manageCompany: 'Open company',
+      companiesTitle: 'Company branded sites',
+      languageLabel: 'Language',
+      hero: 'Hero',
+      surface: 'Surface',
+      companySection: 'Operator card',
+      renterSection: 'Renter card',
+      valueSection: 'Value blocks',
+      featureSection: 'Feature list',
+      stepsSection: 'Launch steps',
+      closingSection: 'Closing call to action',
+      previewTitle: 'Live preview',
+      previewDescription: 'Draft changes appear here before you save them.',
+      homepageSections: 'Homepage sections',
+      homepageSectionsDescription: 'Add or remove blocks from the main marketplace homepage.',
+      addSection: 'Add',
+      removeSection: 'Remove',
+      expand: 'Expand',
+      collapse: 'Collapse',
+    },
+    fr: {
+      title: 'Configuration du site',
+      description: 'Modifiez ici la page d’accueil principale de la marketplace, ou ouvrez une entreprise pour gérer sa page publique et son menu.',
+      homepageTitle: 'Page d’accueil du site principal',
+      homepageDescription: 'Cette section contrôle la page d’accueil marketplace affichée sur le site principal de RentalDriveGo.',
+      saveHomepage: 'Enregistrer la page d’accueil',
+      savingHomepage: 'Enregistrement…',
+      homepageSaved: 'Page d’accueil marketplace enregistrée.',
+      search: 'Rechercher par entreprise ou slug…',
+      loading: 'Chargement…',
+      empty: 'Aucune entreprise trouvée',
+      company: 'Entreprise',
+      slug: 'Slug',
+      status: 'Statut',
+      actions: 'Actions',
+      configure: 'Configurer le site',
+      manageCompany: 'Ouvrir l’entreprise',
+      companiesTitle: 'Sites de marque des entreprises',
+      languageLabel: 'Langue',
+      hero: 'Bloc principal',
+      surface: 'Bloc marketplace',
+      companySection: 'Bloc opérateur',
+      renterSection: 'Bloc client',
+      valueSection: 'Blocs de valeur',
+      featureSection: 'Liste des fonctionnalités',
+      stepsSection: 'Étapes de lancement',
+      closingSection: 'Appel à l’action final',
+      previewTitle: 'Aperçu en direct',
+      previewDescription: 'Les brouillons apparaissent ici avant l’enregistrement.',
+      homepageSections: 'Sections de la page d’accueil',
+      homepageSectionsDescription: 'Ajoutez ou retirez des blocs de la page d’accueil marketplace principale.',
+      addSection: 'Ajouter',
+      removeSection: 'Retirer',
+      expand: 'Ouvrir',
+      collapse: 'Réduire',
+    },
+    ar: {
+      title: 'إعدادات الموقع',
+      description: 'عدّل الصفحة الرئيسية للموقع الرئيسي هنا، أو افتح شركة لإدارة صفحتها العامة وقائمة التنقل الخاصة بها.',
+      homepageTitle: 'الصفحة الرئيسية للموقع الرئيسي',
+      homepageDescription: 'هذا القسم يتحكم في الصفحة الرئيسية للمنصة على موقع RentalDriveGo الرئيسي.',
+      saveHomepage: 'حفظ الصفحة الرئيسية',
+      savingHomepage: 'جارٍ الحفظ…',
+      homepageSaved: 'تم حفظ الصفحة الرئيسية للمنصة.',
+      search: 'ابحث باسم الشركة أو slug…',
+      loading: 'جارٍ التحميل…',
+      empty: 'لم يتم العثور على شركات',
+      company: 'الشركة',
+      slug: 'Slug',
+      status: 'الحالة',
+      actions: 'الإجراءات',
+      configure: 'إعداد الموقع',
+      manageCompany: 'فتح الشركة',
+      companiesTitle: 'المواقع العامة للشركات',
+      languageLabel: 'اللغة',
+      hero: 'البطاقة الرئيسية',
+      surface: 'قسم المنصة',
+      companySection: 'بطاقة المشغل',
+      renterSection: 'بطاقة المستأجر',
+      valueSection: 'عناصر القيمة',
+      featureSection: 'قائمة الميزات',
+      stepsSection: 'خطوات الإطلاق',
+      closingSection: 'الدعوة الختامية',
+      previewTitle: 'معاينة مباشرة',
+      previewDescription: 'تظهر التغييرات هنا قبل الحفظ.',
+      homepageSections: 'أقسام الصفحة الرئيسية',
+      homepageSectionsDescription: 'أضف أو احذف كتل الصفحة الرئيسية للمنصة.',
+      addSection: 'إضافة',
+      removeSection: 'إزالة',
+      expand: 'توسيع',
+      collapse: 'طي',
+    },
+  }[language]
+
+  const [companies, setCompanies] = useState<Company[]>([])
+  const [filtered, setFiltered] = useState<Company[]>([])
+  const [search, setSearch] = useState('')
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [homepage, setHomepage] = useState<MarketplaceHomepageConfig>(cloneMarketplaceHomepageContent())
+  const [homepageLanguage, setHomepageLanguage] = useState<MarketplaceLanguage>(language)
+  const [homepageSaving, setHomepageSaving] = useState(false)
+  const [homepageMessage, setHomepageMessage] = useState<string | null>(null)
+  const [homepageExpanded, setHomepageExpanded] = useState(false)
+
+  useEffect(() => {
+    setHomepageLanguage(language)
+  }, [language])
+
+  useEffect(() => {
+    async function fetchData() {
+      try {
+        const [companiesRes, homepageRes] = await Promise.all([
+          fetch(`${ADMIN_API_BASE}/admin/companies`, {
+            credentials: 'include',
+            cache: 'no-store',
+          }),
+          fetch(`${ADMIN_API_BASE}/admin/site-config/marketplace-homepage`, {
+            credentials: 'include',
+            cache: 'no-store',
+          }),
+        ])
+
+        const companiesJson = await companiesRes.json()
+        if (!companiesRes.ok) throw new Error(companiesJson?.message ?? 'Failed to fetch companies')
+        setCompanies(companiesJson.data?.data ?? [])
+        setFiltered(companiesJson.data?.data ?? [])
+
+        const homepageJson = await homepageRes.json()
+        if (homepageRes.ok && homepageJson?.data) {
+          setHomepage(cloneHomepageContent(homepageJson.data as MarketplaceHomepageConfig))
+        }
+      } catch (err: any) {
+        setError(err.message)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchData()
+  }, [])
+
+  useEffect(() => {
+    const q = search.toLowerCase()
+    setFiltered(
+      companies.filter((company) =>
+        company.name.toLowerCase().includes(q)
+        || company.slug.toLowerCase().includes(q)
+        || company.email.toLowerCase().includes(q),
+      ),
+    )
+  }, [search, companies])
+
+  function updateHomepageContent(patch: Partial<MarketplaceHomepageContent>) {
+    setHomepage((current) => ({
+      ...current,
+      [homepageLanguage]: {
+        ...current[homepageLanguage],
+        ...patch,
+      },
+    }))
+  }
+
+  function updateMetric(index: number, label: string) {
+    const metrics = homepage[homepageLanguage].metrics.map((metric, metricIndex) => (
+      metricIndex === index ? { ...metric, label } : metric
+    ))
+    updateHomepageContent({ metrics })
+  }
+
+  function updatePillar(index: number, patch: { title?: string; body?: string }) {
+    const pillars = homepage[homepageLanguage].pillars.map((pillar, pillarIndex) => (
+      pillarIndex === index ? { ...pillar, ...patch } : pillar
+    ))
+    updateHomepageContent({ pillars })
+  }
+
+  function updateStep(index: number, patch: { title?: string; body?: string }) {
+    const steps = homepage[homepageLanguage].steps.map((step, stepIndex) => (
+      stepIndex === index ? { ...step, ...patch } : step
+    ))
+    updateHomepageContent({ steps })
+  }
+
+  function getActiveSections() {
+    return resolveMarketplaceHomepageSections(activeContent.sections)
+  }
+
+  function addHomepageSection(section: MarketplaceHomepageSectionType) {
+    const sections = getActiveSections()
+    if (sections.includes(section)) return
+    updateHomepageContent({ sections: [...sections, section] })
+  }
+
+  function removeHomepageSection(section: MarketplaceHomepageSectionType) {
+    const sections = getActiveSections().filter((item) => item !== section)
+    if (sections.length === 0) return
+    updateHomepageContent({ sections })
+  }
+
+  async function saveHomepage() {
+    setHomepageSaving(true)
+    setHomepageMessage(null)
+    try {
+      const res = await fetch(`${ADMIN_API_BASE}/admin/site-config/marketplace-homepage`, {
+        method: 'PATCH',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        credentials: 'include',
+        body: JSON.stringify({ homepage }),
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.message ?? 'Failed to save homepage')
+      setHomepage(cloneHomepageContent(json.data as MarketplaceHomepageConfig))
+      setHomepageMessage(copy.homepageSaved)
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setHomepageSaving(false)
+    }
+  }
+
+  const activeContent = homepage[homepageLanguage]
+  const activeSections = getActiveSections()
+  const availableSections = HOMEPAGE_SECTIONS.filter((section) => !activeSections.includes(section))
+  const sectionLabels: Record<MarketplaceHomepageSectionType, string> = {
+    hero: copy.hero,
+    surface: copy.surface,
+    pillars: copy.valueSection,
+    audiences: `${copy.companySection} / ${copy.renterSection}`,
+    features: copy.featureSection,
+    howitworks: language === 'fr' ? 'Fonctionnement' : language === 'ar' ? 'كيفية العمل' : 'How it works',
+    steps: copy.stepsSection,
+    testimonials: language === 'fr' ? 'Témoignages' : language === 'ar' ? 'الشهادات' : 'Testimonials',
+    closing: copy.closingSection,
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="rdg-page-heading flex flex-col gap-4 xl:flex-row xl:items-start xl:justify-between">
+        <div>
+          <p className="rdg-page-kicker">{dict.platform}</p>
+          <h1 className="mt-1 text-3xl font-black">{copy.title}</h1>
+          <p className="mt-2 max-w-3xl text-sm text-zinc-500">{copy.description}</p>
+        </div>
+        <input
+          className="w-full rounded-xl border border-zinc-700 bg-zinc-800 px-3 py-2 text-sm text-zinc-100 placeholder:text-zinc-500 focus:outline-none focus:ring-2 focus:ring-orange-500 xl:w-72"
+          placeholder={copy.search}
+          value={search}
+          onChange={(event) => setSearch(event.target.value)}
+        />
+      </div>
+
+      {error ? <div className="panel p-4 text-sm text-red-400">{error}</div> : null}
+
+      <section className="panel p-6">
+        <div className="flex flex-col gap-4 xl:flex-row xl:items-start xl:justify-between">
+          <div>
+            <h2 className="text-base font-semibold text-zinc-100">{copy.homepageTitle}</h2>
+            <p className="mt-1 text-sm text-zinc-500">{copy.homepageDescription}</p>
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="text-xs font-semibold uppercase tracking-[0.16em] text-zinc-500">{copy.languageLabel}</span>
+              {(['en', 'fr', 'ar'] as MarketplaceLanguage[]).map((value) => (
+                <button
+                  key={value}
+                  type="button"
+                  onClick={() => setHomepageLanguage(value)}
+                  className={`rounded-full px-3 py-1.5 text-xs font-semibold transition ${
+                    homepageLanguage === value ? 'bg-emerald-500 text-white' : 'bg-zinc-800 text-zinc-300 hover:bg-zinc-700'
+                  }`}
+                >
+                  {value.toUpperCase()}
+                </button>
+              ))}
+            </div>
+            <button
+              type="button"
+              onClick={() => setHomepageExpanded((current) => !current)}
+              className="rounded-full border border-zinc-700 bg-zinc-900 px-3 py-1.5 text-xs font-semibold text-zinc-200 transition hover:border-zinc-600 hover:bg-zinc-800"
+            >
+              {homepageExpanded ? copy.collapse : copy.expand}
+            </button>
+          </div>
+        </div>
+
+        {homepageExpanded ? (
+          <>
+            {homepageMessage ? <div className="mt-4 rounded-xl border border-emerald-500/30 bg-emerald-500/10 px-4 py-3 text-sm text-emerald-300">{homepageMessage}</div> : null}
+
+            <div className="mt-6 rounded-2xl border border-zinc-800 bg-zinc-950/60 p-4">
+              <h3 className="text-sm font-semibold text-zinc-100">{copy.homepageSections}</h3>
+              <p className="mt-1 text-xs text-zinc-500">{copy.homepageSectionsDescription}</p>
+
+              <div className="mt-4 flex flex-wrap gap-2">
+                {activeSections.map((section) => (
+                  <div key={section} className="inline-flex items-center gap-2 rounded-full border border-zinc-700 bg-zinc-900 px-3 py-1.5 text-xs font-semibold text-zinc-200">
+                    <span>{sectionLabels[section]}</span>
+                    <button
+                      type="button"
+                      onClick={() => removeHomepageSection(section)}
+                      className="rounded-full border border-rose-500/30 bg-rose-500/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-rose-300"
+                    >
+                      {copy.removeSection}
+                    </button>
+                  </div>
+                ))}
+              </div>
+
+              {availableSections.length ? (
+                <div className="mt-4 flex flex-wrap gap-2">
+                  {availableSections.map((section) => (
+                    <button
+                      key={section}
+                      type="button"
+                      onClick={() => addHomepageSection(section)}
+                      className="rounded-full border border-emerald-500/30 bg-emerald-500/10 px-3 py-1.5 text-xs font-semibold text-emerald-300 transition hover:bg-blue-800/20"
+                    >
+                      {copy.addSection} {sectionLabels[section]}
+                    </button>
+                  ))}
+                </div>
+              ) : null}
+            </div>
+
+            <div className="mt-6 rounded-[1.75rem] border border-zinc-800 bg-zinc-950/60 p-4">
+          <div className="flex items-center justify-between gap-4 border-b border-zinc-800 pb-4">
+            <div>
+              <h3 className="text-sm font-semibold text-zinc-100">{copy.previewTitle}</h3>
+              <p className="mt-1 text-xs text-zinc-500">{copy.previewDescription}</p>
+            </div>
+            <span className="rounded-full border border-emerald-500/30 bg-emerald-500/10 px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.18em] text-emerald-300">
+              {homepageLanguage.toUpperCase()}
+            </span>
+          </div>
+
+          <div className="mt-4 overflow-hidden rounded-[1.5rem] border border-stone-200 bg-[linear-gradient(180deg,#f8f5ef_0%,#f4efe6_28%,#fffdf8_58%,#ffffff_100%)] shadow-2xl shadow-black/20">
+            <div className="border-b border-stone-200 bg-white/90 px-5 py-4">
+              <div className="flex flex-wrap items-center justify-between gap-3">
+                <div>
+                  <p className="text-xs font-bold uppercase tracking-[0.32em] text-orange-700">{activeContent.heroKicker}</p>
+                  <p className="mt-2 text-sm text-stone-500">rentaldrivego.com</p>
+                </div>
+                <div className="flex flex-wrap gap-2 text-xs font-semibold text-stone-600">
+                  {activeContent.metrics.map((metric) => (
+                    <span key={metric.value} className="rounded-full border border-stone-300 bg-white px-3 py-1.5">
+                      {metric.label}
+                    </span>
+                  ))}
+                </div>
+              </div>
+            </div>
+
+            <div className="space-y-10 px-5 py-6 lg:px-8">
+              {activeSections.includes('hero') ? <section className="grid gap-6 lg:grid-cols-[1.1fr_0.9fr] lg:items-center">
+                <div>
+                  <h4 className="text-4xl font-black tracking-[-0.04em] text-blue-950">{activeContent.heroTitle}</h4>
+                  <p className="mt-5 max-w-2xl text-base leading-8 text-stone-600">{activeContent.heroBody}</p>
+                  <div className="mt-8 flex flex-wrap gap-3">
+                    <span className="rounded-full bg-orange-600 px-5 py-3 text-sm font-semibold text-white">{activeContent.startTrial}</span>
+                    <span className="rounded-full border border-stone-300 bg-white px-5 py-3 text-sm font-semibold text-stone-700">{activeContent.exploreVehicles}</span>
+                  </div>
+                </div>
+                {activeSections.includes('surface') ? (
+                <div className="rounded-[1.5rem] bg-[#06132e] p-6 text-white">
+                  <div className="flex items-center justify-between gap-3">
+                    <span className="rounded-full border border-white/15 bg-white/10 px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.22em] text-orange-200">
+                      {activeContent.surfaceLabel}
+                    </span>
+                    <span className="rounded-full bg-emerald-400/15 px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.22em] text-emerald-200">
+                      {activeContent.liveLabel}
+                    </span>
+                  </div>
+                  <h5 className="mt-5 text-2xl font-black tracking-[-0.03em]">{activeContent.surfaceTitle}</h5>
+                  <p className="mt-4 text-sm leading-7 text-stone-300">{activeContent.surfaceBody}</p>
+                  <div className="mt-6 space-y-3">
+                    {[activeContent.trustedFleets, activeContent.brandedFlows, activeContent.multiTenant].map((item, index) => (
+                      <div key={`${item}-${index}`} className="rounded-[1.25rem] border border-white/10 bg-white/5 px-4 py-3 text-sm font-semibold">
+                        {item}
+                      </div>
+                    ))}
+                  </div>
+                </div>
+                ) : null}
+              </section> : null}
+
+              {activeSections.includes('surface') && !activeSections.includes('hero') ? (
+              <section className="rounded-[1.5rem] bg-[#06132e] p-6 text-white">
+                <div className="flex items-center justify-between gap-3">
+                  <span className="rounded-full border border-white/15 bg-white/10 px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.22em] text-orange-200">
+                    {activeContent.surfaceLabel}
+                  </span>
+                  <span className="rounded-full bg-emerald-400/15 px-3 py-1 text-[11px] font-semibold uppercase tracking-[0.22em] text-emerald-200">
+                    {activeContent.liveLabel}
+                  </span>
+                </div>
+                <h5 className="mt-5 text-2xl font-black tracking-[-0.03em]">{activeContent.surfaceTitle}</h5>
+                <p className="mt-4 text-sm leading-7 text-stone-300">{activeContent.surfaceBody}</p>
+              </section>
+              ) : null}
+
+              {activeSections.includes('pillars') ? <section className="grid gap-4 lg:grid-cols-3">
+                {activeContent.pillars.map((pillar, index) => (
+                  <article
+                    key={`${pillar.title}-${index}`}
+                    className={`rounded-[1.5rem] border p-5 ${index === 1 ? 'border-orange-700 bg-orange-600 text-white' : 'border-stone-200 bg-white text-stone-900'}`}
+                  >
+                    <p className={`text-xs font-bold uppercase tracking-[0.24em] ${index === 1 ? 'text-stone-300' : 'text-stone-400'}`}>0{index + 1}</p>
+                    <h5 className="mt-3 text-xl font-black">{pillar.title}</h5>
+                    <p className={`mt-3 text-sm leading-7 ${index === 1 ? 'text-stone-200' : 'text-stone-600'}`}>{pillar.body}</p>
+                  </article>
+                ))}
+              </section> : null}
+
+              {activeSections.includes('audiences') ? <section className="grid gap-4 lg:grid-cols-2">
+                <article className="rounded-[1.5rem] border border-stone-200 bg-white p-5">
+                  <p className="text-xs font-bold uppercase tracking-[0.24em] text-stone-500">{activeContent.companyKicker}</p>
+                  <h5 className="mt-3 text-2xl font-black text-blue-950">{activeContent.companyTitle}</h5>
+                  <p className="mt-3 text-sm leading-7 text-stone-600">{activeContent.companyBody}</p>
+                </article>
+                <article className="rounded-[1.5rem] border border-stone-200 bg-[#f7efe2] p-5">
+                  <p className="text-xs font-bold uppercase tracking-[0.24em] text-orange-700">{activeContent.renterKicker}</p>
+                  <h5 className="mt-3 text-2xl font-black text-blue-950">{activeContent.renterTitle}</h5>
+                  <p className="mt-3 text-sm leading-7 text-stone-700">{activeContent.renterBody}</p>
+                </article>
+              </section> : null}
+
+              {(activeSections.includes('features') || activeSections.includes('steps')) ? <section className="grid gap-6 lg:grid-cols-[0.9fr_1.1fr]">
+                {activeSections.includes('features') ? (
+                <article className="rounded-[1.5rem] border border-stone-200 bg-[#fffdf8] p-5">
+                  <p className="text-xs font-bold uppercase tracking-[0.24em] text-stone-500">{activeContent.featureLabel}</p>
+                  <div className="mt-5 space-y-3">
+                    {activeContent.features.map((feature, index) => (
+                      <div key={`${feature}-${index}`} className="flex items-start gap-3 rounded-[1rem] border border-stone-200 bg-white px-4 py-3">
+                        <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-orange-600 text-xs font-bold text-white">
+                          {index + 1}
+                        </span>
+                        <p className="text-sm font-semibold leading-6 text-stone-800">{feature}</p>
+                      </div>
+                    ))}
+                  </div>
+                </article>
+                ) : <div />}
+                {activeSections.includes('steps') ? (
+                <article className="rounded-[1.5rem] border border-stone-200 bg-white p-5">
+                  <p className="text-xs font-bold uppercase tracking-[0.24em] text-orange-700">{activeContent.readyKicker}</p>
+                  <h5 className="mt-3 text-2xl font-black text-blue-950">{activeContent.stepsTitle}</h5>
+                  <div className="mt-5 space-y-3">
+                    {activeContent.steps.map((step) => (
+                      <div key={step.step} className="rounded-[1rem] border border-stone-200 bg-stone-50 p-4">
+                        <p className="text-xs font-bold uppercase tracking-[0.24em] text-stone-500">{activeContent.stepLabel} {step.step}</p>
+                        <h6 className="mt-2 text-lg font-black text-blue-950">{step.title}</h6>
+                        <p className="mt-2 text-sm leading-7 text-stone-600">{step.body}</p>
+                      </div>
+                    ))}
+                  </div>
+                </article>
+                ) : <div />}
+              </section> : null}
+
+              {activeSections.includes('closing') ? <section className="rounded-[1.5rem] bg-[#06132e] px-6 py-7 text-white">
+                <p className="text-xs font-bold uppercase tracking-[0.28em] text-orange-300">{activeContent.readyKicker}</p>
+                <h5 className="mt-4 max-w-3xl text-3xl font-black tracking-[-0.04em]">{activeContent.readyTitle}</h5>
+                <p className="mt-4 max-w-2xl text-sm leading-8 text-stone-300">{activeContent.readyBody}</p>
+                <div className="mt-6 flex flex-wrap gap-3">
+                  <span className="rounded-full border border-white/20 px-5 py-3 text-sm font-semibold">{activeContent.viewPricing}</span>
+                  <span className="rounded-full bg-orange-300 px-5 py-3 text-sm font-semibold text-blue-950">{activeContent.createWorkspace}</span>
+                </div>
+              </section> : null}
+            </div>
+          </div>
+            </div>
+
+            <div className="mt-6 space-y-8">
+            <div className="grid gap-4 md:grid-cols-2">
+              <label>
+                <span className={LABEL_CLASS}>Brand kicker</span>
+                <input className={INPUT_CLASS} value={activeContent.heroKicker} onChange={(event) => updateHomepageContent({ heroKicker: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Primary CTA</span>
+                <input className={INPUT_CLASS} value={activeContent.startTrial} onChange={(event) => updateHomepageContent({ startTrial: event.target.value })} />
+              </label>
+              <label className="md:col-span-2">
+                <span className={LABEL_CLASS}>{copy.hero} title</span>
+                <input className={INPUT_CLASS} value={activeContent.heroTitle} onChange={(event) => updateHomepageContent({ heroTitle: event.target.value })} />
+              </label>
+              <label className="md:col-span-2">
+                <span className={LABEL_CLASS}>{copy.hero} body</span>
+                <textarea className={`${INPUT_CLASS} min-h-24`} value={activeContent.heroBody} onChange={(event) => updateHomepageContent({ heroBody: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Secondary CTA</span>
+                <input className={INPUT_CLASS} value={activeContent.exploreVehicles} onChange={(event) => updateHomepageContent({ exploreVehicles: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.surface} badge</span>
+                <input className={INPUT_CLASS} value={activeContent.surfaceLabel} onChange={(event) => updateHomepageContent({ surfaceLabel: event.target.value })} />
+              </label>
+            </div>
+
+            <div className="grid gap-4 md:grid-cols-2">
+              <label className="md:col-span-2">
+                <span className={LABEL_CLASS}>{copy.surface} title</span>
+                <input className={INPUT_CLASS} value={activeContent.surfaceTitle} onChange={(event) => updateHomepageContent({ surfaceTitle: event.target.value })} />
+              </label>
+              <label className="md:col-span-2">
+                <span className={LABEL_CLASS}>{copy.surface} body</span>
+                <textarea className={`${INPUT_CLASS} min-h-24`} value={activeContent.surfaceBody} onChange={(event) => updateHomepageContent({ surfaceBody: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Live label</span>
+                <input className={INPUT_CLASS} value={activeContent.liveLabel} onChange={(event) => updateHomepageContent({ liveLabel: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Trusted fleets</span>
+                <input className={INPUT_CLASS} value={activeContent.trustedFleets} onChange={(event) => updateHomepageContent({ trustedFleets: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Branded flows</span>
+                <input className={INPUT_CLASS} value={activeContent.brandedFlows} onChange={(event) => updateHomepageContent({ brandedFlows: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>Multi-tenant</span>
+                <input className={INPUT_CLASS} value={activeContent.multiTenant} onChange={(event) => updateHomepageContent({ multiTenant: event.target.value })} />
+              </label>
+            </div>
+
+            <div className="grid gap-4 md:grid-cols-2">
+              <label>
+                <span className={LABEL_CLASS}>{copy.companySection} kicker</span>
+                <input className={INPUT_CLASS} value={activeContent.companyKicker} onChange={(event) => updateHomepageContent({ companyKicker: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.renterSection} kicker</span>
+                <input className={INPUT_CLASS} value={activeContent.renterKicker} onChange={(event) => updateHomepageContent({ renterKicker: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.companySection} title</span>
+                <input className={INPUT_CLASS} value={activeContent.companyTitle} onChange={(event) => updateHomepageContent({ companyTitle: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.renterSection} title</span>
+                <input className={INPUT_CLASS} value={activeContent.renterTitle} onChange={(event) => updateHomepageContent({ renterTitle: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.companySection} body</span>
+                <textarea className={`${INPUT_CLASS} min-h-24`} value={activeContent.companyBody} onChange={(event) => updateHomepageContent({ companyBody: event.target.value })} />
+              </label>
+              <label>
+                <span className={LABEL_CLASS}>{copy.renterSection} body</span>
+                <textarea className={`${INPUT_CLASS} min-h-24`} value={activeContent.renterBody} onChange={(event) => updateHomepageContent({ renterBody: event.target.value })} />
+              </label>
+            </div>
+
+            <div className="grid gap-6 xl:grid-cols-2">
+              <div className="space-y-4">
+                <h3 className="text-sm font-semibold text-zinc-200">{copy.valueSection}</h3>
+                <div className="grid gap-4">
+                  {activeContent.metrics.map((metric, index) => (
+                    <label key={metric.value}>
+                      <span className={LABEL_CLASS}>Metric {metric.value}</span>
+                      <input className={INPUT_CLASS} value={metric.label} onChange={(event) => updateMetric(index, event.target.value)} />
+                    </label>
+                  ))}
+                  {activeContent.pillars.map((pillar, index) => (
+                    <div key={`${pillar.title}-${index}`} className="grid gap-4 rounded-2xl border border-zinc-800 bg-zinc-950/50 p-4">
+                      <label>
+                        <span className={LABEL_CLASS}>Pillar {index + 1} title</span>
+                        <input className={INPUT_CLASS} value={pillar.title} onChange={(event) => updatePillar(index, { title: event.target.value })} />
+                      </label>
+                      <label>
+                        <span className={LABEL_CLASS}>Pillar {index + 1} body</span>
+                        <textarea className={`${INPUT_CLASS} min-h-24`} value={pillar.body} onChange={(event) => updatePillar(index, { body: event.target.value })} />
+                      </label>
+                    </div>
+                  ))}
+                </div>
+              </div>
+
+              <div className="space-y-4">
+                <h3 className="text-sm font-semibold text-zinc-200">{copy.featureSection}</h3>
+                <label>
+                  <span className={LABEL_CLASS}>Feature section label</span>
+                  <input className={INPUT_CLASS} value={activeContent.featureLabel} onChange={(event) => updateHomepageContent({ featureLabel: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Features, one per line</span>
+                  <textarea
+                    className={`${INPUT_CLASS} min-h-40`}
+                    value={activeContent.features.join('\n')}
+                    onChange={(event) => updateHomepageContent({ features: event.target.value.split('\n').map((item) => item.trim()).filter(Boolean) })}
+                  />
+                </label>
+              </div>
+            </div>
+
+            <div className="grid gap-6 xl:grid-cols-2">
+              <div className="space-y-4">
+                <h3 className="text-sm font-semibold text-zinc-200">{copy.stepsSection}</h3>
+                <label>
+                  <span className={LABEL_CLASS}>Steps title</span>
+                  <input className={INPUT_CLASS} value={activeContent.stepsTitle} onChange={(event) => updateHomepageContent({ stepsTitle: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Step label</span>
+                  <input className={INPUT_CLASS} value={activeContent.stepLabel} onChange={(event) => updateHomepageContent({ stepLabel: event.target.value })} />
+                </label>
+                {activeContent.steps.map((step, index) => (
+                  <div key={step.step} className="grid gap-4 rounded-2xl border border-zinc-800 bg-zinc-950/50 p-4">
+                    <p className="text-xs font-semibold uppercase tracking-[0.16em] text-zinc-500">Step {step.step}</p>
+                    <label>
+                      <span className={LABEL_CLASS}>Title</span>
+                      <input className={INPUT_CLASS} value={step.title} onChange={(event) => updateStep(index, { title: event.target.value })} />
+                    </label>
+                    <label>
+                      <span className={LABEL_CLASS}>Body</span>
+                      <textarea className={`${INPUT_CLASS} min-h-24`} value={step.body} onChange={(event) => updateStep(index, { body: event.target.value })} />
+                    </label>
+                  </div>
+                ))}
+              </div>
+
+              <div className="space-y-4">
+                <h3 className="text-sm font-semibold text-zinc-200">{copy.closingSection}</h3>
+                <label>
+                  <span className={LABEL_CLASS}>Closing kicker</span>
+                  <input className={INPUT_CLASS} value={activeContent.readyKicker} onChange={(event) => updateHomepageContent({ readyKicker: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Closing title</span>
+                  <input className={INPUT_CLASS} value={activeContent.readyTitle} onChange={(event) => updateHomepageContent({ readyTitle: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Closing body</span>
+                  <textarea className={`${INPUT_CLASS} min-h-24`} value={activeContent.readyBody} onChange={(event) => updateHomepageContent({ readyBody: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Pricing CTA</span>
+                  <input className={INPUT_CLASS} value={activeContent.viewPricing} onChange={(event) => updateHomepageContent({ viewPricing: event.target.value })} />
+                </label>
+                <label>
+                  <span className={LABEL_CLASS}>Workspace CTA</span>
+                  <input className={INPUT_CLASS} value={activeContent.createWorkspace} onChange={(event) => updateHomepageContent({ createWorkspace: event.target.value })} />
+                </label>
+              </div>
+            </div>
+            </div>
+
+            <div className="mt-6 flex justify-end">
+              <button
+                type="button"
+                onClick={saveHomepage}
+                disabled={homepageSaving}
+                className="rounded-xl bg-blue-700 px-4 py-2 text-sm font-semibold text-white transition hover:bg-blue-800 disabled:cursor-not-allowed disabled:opacity-60"
+              >
+                {homepageSaving ? copy.savingHomepage : copy.saveHomepage}
+              </button>
+            </div>
+          </>
+        ) : null}
+      </section>
+
+      <section className="panel overflow-hidden">
+        <div className="border-b border-zinc-800 px-6 py-4">
+          <h2 className="text-base font-semibold text-zinc-100">{copy.companiesTitle}</h2>
+        </div>
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-zinc-800">
+                <th className="px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">{copy.company}</th>
+                <th className="px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">{copy.slug}</th>
+                <th className="px-6 py-3 text-left text-xs font-medium uppercase tracking-wider text-zinc-500">{copy.status}</th>
+                <th className="px-6 py-3 text-right text-xs font-medium uppercase tracking-wider text-zinc-500">{copy.actions}</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-zinc-800/60">
+              {loading ? (
+                <tr>
+                  <td colSpan={4} className="px-6 py-12 text-center text-zinc-500">{copy.loading}</td>
+                </tr>
+              ) : filtered.length === 0 ? (
+                <tr>
+                  <td colSpan={4} className="px-6 py-12 text-center text-zinc-500">{copy.empty}</td>
+                </tr>
+              ) : filtered.map((company) => (
+                <tr key={company.id} className="transition-colors hover:bg-zinc-800/30">
+                  <td className="px-6 py-4">
+                    <p className="font-medium text-zinc-100">{company.brand?.displayName ?? company.name}</p>
+                    <p className="text-xs text-zinc-500">{company.email}</p>
+                  </td>
+                  <td className="px-6 py-4 font-mono text-xs text-zinc-400">{company.slug}</td>
+                  <td className="px-6 py-4">
+                    <span className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium ${STATUS_COLORS[company.status] ?? 'text-zinc-400 bg-zinc-800'}`}>
+                      {company.status}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4">
+                    <div className="flex justify-end gap-2">
+                      <Link
+                        href={`/dashboard/companies/${company.id}#site-config`}
+                        className="rounded-lg bg-blue-700 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-blue-800"
+                      >
+                        {copy.configure}
+                      </Link>
+                      <Link
+                        href={`/dashboard/companies/${company.id}`}
+                        className="rounded-lg bg-zinc-800 px-3 py-1.5 text-xs font-medium text-zinc-200 transition-colors hover:bg-zinc-700"
+                      >
+                        {copy.manageCompany}
+                      </Link>
+                    </div>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </section>
+    </div>
+  )
+}
@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const nextServer = vi.hoisted(() => ({
+  redirect: vi.fn((url: URL) => ({ kind: 'redirect', url: url.toString() })),
+}))
+
+vi.mock('next/server', () => ({
+  NextResponse: {
+    redirect: nextServer.redirect,
+  },
+}))
+
+describe('admin favicon route', () => {
+  it('redirects favicon requests to the generated icon route on the same origin', async () => {
+    const { GET } = await import('./route')
+
+    const response = GET(new Request('https://admin.example.com/favicon.ico'))
+
+    expect(response).toEqual({ kind: 'redirect', url: 'https://admin.example.com/icon' })
+    expect(nextServer.redirect).toHaveBeenCalledTimes(1)
+  })
+
+  it('preserves forwarded path base through the request URL origin only', async () => {
+    const { GET } = await import('./route')
+
+    const response = GET(new Request('https://admin.example.com/admin/favicon.ico'))
+
+    expect(response).toEqual({ kind: 'redirect', url: 'https://admin.example.com/icon' })
+  })
+})
@@ -0,0 +1,6 @@
+import { NextResponse } from 'next/server'
+
+export function GET(request: Request) {
+  const url = new URL('/icon', request.url)
+  return NextResponse.redirect(url)
+}
@@ -0,0 +1,32 @@
+import { ImageResponse } from 'next/og'
+
+export const size = {
+  width: 32,
+  height: 32,
+}
+
+export const contentType = 'image/png'
+
+export default function Icon() {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: '#111827',
+          color: '#ffffff',
+          fontSize: 18,
+          fontWeight: 700,
+          borderRadius: 8,
+        }}
+      >
+        A
+      </div>
+    ),
+    size,
+  )
+}
@@ -0,0 +1,24 @@
+import type { Metadata } from 'next'
+import { AdminI18nProvider } from '@/components/I18nProvider'
+import './globals.css'
+
+export const metadata: Metadata = {
+  title: 'RentalDriveGo Admin',
+  description: 'RentalDriveGo platform administration.',
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className="light" suppressHydrationWarning>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              "(function(){try{var m=document.cookie.match(/(?:^|; )rentaldrivego-theme=([^;]+)/);var theme=m?decodeURIComponent(m[1]):(localStorage.getItem('rentaldrivego-theme')||localStorage.getItem('admin-theme'));if(theme!=='light'&&theme!=='dark'){theme=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light'}document.documentElement.classList.remove('light','dark');document.documentElement.classList.add(theme);document.documentElement.style.colorScheme=theme;document.body&&document.body.setAttribute('data-theme',theme)}catch(e){}})();",
+          }}
+        />
+      </head>
+      <body suppressHydrationWarning><AdminI18nProvider>{children}</AdminI18nProvider></body>
+    </html>
+  )
+}
@@ -0,0 +1,13 @@
+import { headers } from 'next/headers'
+import { redirect } from 'next/navigation'
+import { resolveServerAppUrl } from '@/lib/appUrls'
+
+export default async function AdminLoginPage() {
+  const requestHeaders = await headers()
+  const dashboardUrl = resolveServerAppUrl(
+    process.env.NEXT_PUBLIC_DASHBOARD_URL ?? 'http://localhost:3000/dashboard',
+    requestHeaders.get('host'),
+    requestHeaders.get('x-forwarded-proto'),
+  )
+  redirect(`${dashboardUrl}/sign-in?portal=admin&next=/dashboard`)
+}
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation'
+
+export default function AdminRootPage() {
+  redirect('/login')
+}
@@ -0,0 +1,18 @@
+import { describe, expect, it, vi } from 'vitest'
+
+const navigation = vi.hoisted(() => ({
+  redirect: vi.fn((path: string) => {
+    throw new Error(`NEXT_REDIRECT:${path}`)
+  }),
+}))
+
+vi.mock('next/navigation', () => navigation)
+
+import AdminRootPage from './page'
+
+describe('admin public redirects', () => {
+  it('sends the admin root to the login page', () => {
+    expect(() => AdminRootPage()).toThrow('NEXT_REDIRECT:/login')
+    expect(navigation.redirect).toHaveBeenCalledWith('/login')
+  })
+})
@@ -0,0 +1,311 @@
+'use client'
+
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react'
+
+export type AdminLanguage = 'en' | 'fr' | 'ar'
+export type AdminTheme = 'light' | 'dark'
+
+type AdminDictionary = {
+  nav: Record<string, string>
+  logout: string
+  language: string
+  theme: string
+  light: string
+  dark: string
+  overview: string
+  admin: string
+  platform: string
+  loading: string
+}
+
+const dictionaries: Record<AdminLanguage, AdminDictionary> = {
+  en: {
+    nav: {
+      overview: 'Overview',
+      companies: 'Companies',
+      siteConfig: 'Site Config',
+      renters: 'Renters',
+      auditLogs: 'Audit Logs',
+      adminUsers: 'Admin Users',
+      billing: 'Billing',
+      pricing: 'Pricing',
+      notifications: 'Notifications',
+      menuManagement: 'Menu Management',
+    },
+    logout: 'Logout',
+    language: 'Language',
+    theme: 'Theme',
+    light: 'Light',
+    dark: 'Dark',
+    overview: 'Platform overview',
+    admin: 'Admin',
+    platform: 'Platform',
+    loading: 'Loading',
+  },
+  fr: {
+    nav: {
+      overview: "Vue d'ensemble",
+      companies: 'Entreprises',
+      siteConfig: 'Config site',
+      renters: 'Locataires',
+      auditLogs: "Journaux d'audit",
+      adminUsers: 'Utilisateurs admin',
+      billing: 'Facturation',
+      pricing: 'Tarification',
+      notifications: 'Notifications',
+      menuManagement: 'Gestion du menu',
+    },
+    logout: 'Déconnexion',
+    language: 'Langue',
+    theme: 'Mode',
+    light: 'Clair',
+    dark: 'Sombre',
+    overview: 'Vue plateforme',
+    admin: 'Admin',
+    platform: 'Plateforme',
+    loading: 'Chargement',
+  },
+  ar: {
+    nav: {
+      overview: 'نظرة عامة',
+      companies: 'الشركات',
+      siteConfig: 'إعدادات الموقع',
+      renters: 'المستأجرون',
+      auditLogs: 'سجلات التدقيق',
+      adminUsers: 'مستخدمو الإدارة',
+      billing: 'الفوترة',
+      pricing: 'الأسعار',
+      notifications: 'الإشعارات',
+      menuManagement: 'إدارة القوائم',
+    },
+    logout: 'تسجيل الخروج',
+    language: 'اللغة',
+    theme: 'الوضع',
+    light: 'فاتح',
+    dark: 'داكن',
+    overview: 'نظرة عامة على المنصة',
+    admin: 'الإدارة',
+    platform: 'المنصة',
+    loading: 'جارٍ التحميل',
+  },
+}
+
+const languageMeta = {
+  en: { flag: '🇺🇸', shortLabel: 'EN' },
+  fr: { flag: '🇫🇷', shortLabel: 'FR' },
+  ar: { flag: '🇲🇦', shortLabel: 'AR' },
+} as const
+
+const SHARED_THEME_KEY = 'rentaldrivego-theme'
+
+type AdminI18nContext = {
+  language: AdminLanguage
+  setLanguage: (value: AdminLanguage) => void
+  theme: AdminTheme
+  setTheme: (value: AdminTheme) => void
+  dict: AdminDictionary
+}
+
+const Context = createContext<AdminI18nContext | null>(null)
+
+export function AdminI18nProvider({ children }: { children: React.ReactNode }) {
+  const [language, setLanguage] = useState<AdminLanguage>('en')
+  const [theme, setTheme] = useState<AdminTheme>('light')
+  // Skip the very first write so we don't overwrite a stored preference with
+  // the default 'en' value before the hydration read-effect has applied it.
+  const skipFirstLangWrite = useRef(true)
+
+  useEffect(() => {
+    const stored = window.localStorage.getItem('admin-language')
+    const storedTheme = window.localStorage.getItem(SHARED_THEME_KEY) ?? window.localStorage.getItem('admin-theme')
+    if (stored === 'en' || stored === 'fr' || stored === 'ar') {
+      setLanguage(stored)
+    }
+
+    if (storedTheme === 'light' || storedTheme === 'dark') {
+      setTheme(storedTheme)
+      return
+    }
+
+    if (!window.matchMedia('(prefers-color-scheme: dark)').matches) {
+      setTheme('light')
+    }
+  }, [])
+
+  useEffect(() => {
+    document.documentElement.lang = language
+    document.documentElement.dir = language === 'ar' ? 'rtl' : 'ltr'
+    if (skipFirstLangWrite.current) {
+      skipFirstLangWrite.current = false
+      return
+    }
+    window.localStorage.setItem('admin-language', language)
+  }, [language])
+
+  useEffect(() => {
+    document.documentElement.classList.remove('light', 'dark')
+    document.documentElement.classList.add(theme)
+    document.documentElement.style.colorScheme = theme
+    document.body.dataset.theme = theme
+    document.cookie = `${SHARED_THEME_KEY}=${encodeURIComponent(theme)}; path=/; max-age=31536000; SameSite=Lax`
+    window.localStorage.setItem(SHARED_THEME_KEY, theme)
+    window.localStorage.setItem('admin-theme', theme)
+  }, [theme])
+
+  const value = useMemo(
+    () => ({ language, setLanguage, theme, setTheme, dict: dictionaries[language] }),
+    [language, theme],
+  )
+  return <Context.Provider value={value}>{children}</Context.Provider>
+}
+
+export function useAdminI18n() {
+  const context = useContext(Context)
+  if (!context) throw new Error('useAdminI18n must be used within AdminI18nProvider')
+  return context
+}
+
+export function AdminLanguageSwitcher() {
+  const { language, setLanguage } = useAdminI18n()
+  const [open, setOpen] = useState(false)
+  const [embedded, setEmbedded] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    setEmbedded(window.self !== window.top)
+  }, [])
+
+  useEffect(() => {
+    if (!open) return
+    function onMouseDown(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', onMouseDown)
+    return () => document.removeEventListener('mousedown', onMouseDown)
+  }, [open])
+
+  if (embedded) return null
+
+  const current = languageMeta[language]
+
+  return (
+    <div ref={ref} className="relative flex-1">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="flex w-full items-center justify-between gap-1.5 rounded-xl border border-stone-200/80 bg-white/95 px-3 py-2 text-xs font-semibold text-stone-700 shadow-sm transition hover:bg-stone-50 dark:border-blue-800 dark:bg-[#0d1b38]/85 dark:text-stone-200 dark:hover:bg-[#162038]"
+      >
+        <span className="flex items-center gap-1.5">
+          <span aria-hidden="true">{current.flag}</span>
+          <span>{current.shortLabel}</span>
+        </span>
+        <svg className={`h-3 w-3 text-stone-400 transition-transform dark:text-stone-500 ${open ? 'rotate-180' : ''}`} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+        </svg>
+      </button>
+
+      {open && (
+        <div className="absolute bottom-full left-0 mb-1.5 w-full overflow-hidden rounded-xl border border-stone-200/80 bg-white shadow-lg dark:border-blue-800 dark:bg-[#0d1b38]">
+          {(['en', 'fr', 'ar'] as AdminLanguage[]).map((value) => {
+            const meta = languageMeta[value]
+            const active = value === language
+            return (
+              <button
+                key={value}
+                type="button"
+                onClick={() => { setLanguage(value); setOpen(false) }}
+                className={`flex w-full items-center gap-2 px-3 py-2 text-xs font-semibold transition-colors ${
+                  active
+                    ? 'bg-blue-900 text-white dark:bg-orange-500 dark:text-white'
+                    : 'text-stone-700 hover:bg-stone-100 dark:text-stone-200 dark:hover:bg-[#162038]'
+                }`}
+              >
+                <span aria-hidden="true">{meta.flag}</span>
+                <span>{meta.shortLabel}</span>
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function AdminThemeSwitcher() {
+  const { theme, setTheme, dict } = useAdminI18n()
+  const [open, setOpen] = useState(false)
+  const [embedded, setEmbedded] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    setEmbedded(window.self !== window.top)
+  }, [])
+
+  useEffect(() => {
+    if (!open) return
+    function onMouseDown(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', onMouseDown)
+    return () => document.removeEventListener('mousedown', onMouseDown)
+  }, [open])
+
+  if (embedded) return null
+
+  return (
+    <div ref={ref} className="relative flex-1">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className="flex w-full items-center justify-between gap-1.5 rounded-xl border border-stone-200/80 bg-white/95 px-3 py-2 text-xs font-semibold text-stone-700 shadow-sm transition hover:bg-stone-50 dark:border-blue-800 dark:bg-[#0d1b38]/85 dark:text-stone-200 dark:hover:bg-[#162038]"
+      >
+        <span className="flex items-center gap-1.5">
+          {theme === 'light' ? (
+            <svg className="h-3.5 w-3.5 text-orange-500" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M12 3v2.25m6.364.386-1.591 1.591M21 12h-2.25m-.386 6.364-1.591-1.591M12 18.75V21m-4.773-4.227-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 1 1-7.5 0 3.75 3.75 0 0 1 7.5 0Z" />
+            </svg>
+          ) : (
+            <svg className="h-3.5 w-3.5 text-blue-300" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M21.752 15.002A9.72 9.72 0 0 1 18 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 0 0 3 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 0 0 9.002-5.998Z" />
+            </svg>
+          )}
+          <span>{theme === 'light' ? dict.light : dict.dark}</span>
+        </span>
+        <svg className={`h-3 w-3 text-stone-400 transition-transform dark:text-stone-500 ${open ? 'rotate-180' : ''}`} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+        </svg>
+      </button>
+
+      {open && (
+        <div className="absolute bottom-full left-0 mb-1.5 w-full overflow-hidden rounded-xl border border-stone-200/80 bg-white shadow-lg dark:border-blue-800 dark:bg-[#0d1b38]">
+          {(['light', 'dark'] as AdminTheme[]).map((value) => {
+            const active = value === theme
+            return (
+              <button
+                key={value}
+                type="button"
+                onClick={() => { setTheme(value); setOpen(false) }}
+                className={`flex w-full items-center gap-2 px-3 py-2 text-xs font-semibold transition-colors ${
+                  active
+                    ? 'bg-blue-900 text-white dark:bg-orange-500 dark:text-white'
+                    : 'text-stone-700 hover:bg-stone-100 dark:text-stone-200 dark:hover:bg-[#162038]'
+                }`}
+              >
+                {value === 'light' ? (
+                  <svg className="h-3.5 w-3.5 text-orange-500" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M12 3v2.25m6.364.386-1.591 1.591M21 12h-2.25m-.386 6.364-1.591-1.591M12 18.75V21m-4.773-4.227-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 1 1-7.5 0 3.75 3.75 0 0 1 7.5 0Z" />
+                  </svg>
+                ) : (
+                  <svg className="h-3.5 w-3.5 text-blue-300" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M21.752 15.002A9.72 9.72 0 0 1 18 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 0 0 3 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 0 0 9.002-5.998Z" />
+                  </svg>
+                )}
+                <span className={active ? 'text-inherit' : ''}>{value === 'light' ? dict.light : dict.dark}</span>
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
@@ -0,0 +1,47 @@
+'use client'
+
+import {
+  AdminLanguageSwitcher,
+  AdminThemeSwitcher,
+  useAdminI18n,
+} from '@/components/I18nProvider'
+
+const languageMeta = {
+  en: { flag: '🇺🇸', shortLabel: 'EN' },
+  fr: { flag: '🇫🇷', shortLabel: 'FR' },
+  ar: { flag: '🇲🇦', shortLabel: 'AR' },
+} as const
+
+export default function PublicFooter() {
+  const { language } = useAdminI18n()
+  const currentLanguage = languageMeta[language]
+  const dict = {
+    en: {
+      preferences: 'Admin preferences',
+    },
+    fr: {
+      preferences: 'Préférences d’administration',
+    },
+    ar: {
+      preferences: 'تفضيلات الإدارة',
+    },
+  }[language]
+
+  return (
+    <footer className="border-t border-stone-200/80 bg-white/72 px-4 py-4 backdrop-blur-xl transition-colors dark:border-blue-900 dark:bg-[#07101e]/72">
+      <div className="mx-auto flex max-w-6xl flex-col items-center justify-between gap-3 lg:flex-row">
+        <div className="flex items-center gap-3 text-xs font-medium uppercase tracking-[0.16em] text-stone-400 dark:text-stone-500">
+          <p>{dict.preferences}</p>
+          <span className="inline-flex items-center gap-1 rounded-full border border-stone-200/80 bg-white/95 px-2.5 py-1 text-stone-700 dark:border-blue-800 dark:bg-[#0d1b38]/85 dark:text-stone-200">
+            <span aria-hidden="true">{currentLanguage.flag}</span>
+            <span>{currentLanguage.shortLabel}</span>
+          </span>
+        </div>
+        <div className="flex flex-col items-center gap-3 sm:flex-row">
+          <AdminLanguageSwitcher />
+          <AdminThemeSwitcher />
+        </div>
+      </div>
+    </footer>
+  )
+}
@@ -0,0 +1,49 @@
+'use client'
+
+import Link from 'next/link'
+import { useAdminI18n } from '@/components/I18nProvider'
+
+const languageMeta = {
+  en: { flag: '🇺🇸', shortLabel: 'EN' },
+  fr: { flag: '🇫🇷', shortLabel: 'FR' },
+  ar: { flag: '🇲🇦', shortLabel: 'AR' },
+} as const
+
+export default function PublicHeader() {
+  const { language } = useAdminI18n()
+  const currentLanguage = languageMeta[language]
+  const dict = {
+    en: {
+      admin: 'Admin Console',
+      signIn: 'Sign in',
+    },
+    fr: {
+      admin: 'Console admin',
+      signIn: 'Connexion',
+    },
+    ar: {
+      admin: 'لوحة الإدارة',
+      signIn: 'تسجيل الدخول',
+    },
+  }[language]
+
+  return (
+    <header className="sticky top-0 z-30 border-b border-stone-200/80 bg-white/78 backdrop-blur-xl transition-colors dark:border-blue-900 dark:bg-[#07101e]/76">
+      <div className="mx-auto flex max-w-6xl items-center justify-between gap-4 px-4 py-4">
+        <Link href="/" className="flex items-center gap-3">
+          <span className="text-xs font-semibold uppercase tracking-[0.24em] text-orange-700 dark:text-orange-300">RentalDriveGo</span>
+          <span className="hidden text-sm font-semibold text-stone-500 dark:text-stone-400 sm:inline">{dict.admin}</span>
+        </Link>
+        <nav className="flex items-center gap-2">
+          <span className="inline-flex min-w-[3.5rem] items-center justify-center gap-1 rounded-full border border-stone-200/80 bg-white/95 px-2.5 py-2 text-xs font-semibold text-stone-700 dark:border-blue-800 dark:bg-[#0d1b38]/85 dark:text-stone-200">
+            <span aria-hidden="true">{currentLanguage.flag}</span>
+            <span>{currentLanguage.shortLabel}</span>
+          </span>
+          <Link href="/login" className="rounded-full bg-blue-900 px-4 py-2 text-sm font-semibold text-white transition hover:bg-orange-700 dark:bg-orange-400 dark:text-white dark:hover:bg-orange-300">
+            {dict.signIn}
+          </Link>
+        </nav>
+      </div>
+    </header>
+  )
+}
@@ -0,0 +1,31 @@
+import React, { isValidElement } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/components/PublicHeader', () => ({ default: function MockAdminHeader() { return React.createElement('admin-header') } }))
+vi.mock('@/components/PublicFooter', () => ({ default: function MockAdminFooter() { return React.createElement('admin-footer') } }))
+
+import PublicShell from './PublicShell'
+
+function childTypes(node: React.ReactElement): string[] {
+  return React.Children.toArray(node.props.children).filter(isValidElement).map((child) => {
+    const type = child.type as any
+    if (typeof type === 'string') return type
+    return type.displayName ?? type.name ?? 'anonymous'
+  })
+}
+
+describe('admin PublicShell', () => {
+  it('always renders the admin public chrome around children', () => {
+    const shell = PublicShell({ children: React.createElement('section', { id: 'login' }) })
+
+    expect(childTypes(shell)).toEqual(['MockAdminHeader', 'div', 'MockAdminFooter'])
+  })
+
+  it('uses a flex column root so footer placement stays stable', () => {
+    const shell = PublicShell({ children: React.createElement('section') })
+
+    expect(shell.props.className).toContain('flex')
+    expect(shell.props.className).toContain('min-h-screen')
+    expect(shell.props.className).toContain('flex-col')
+  })
+})
@@ -0,0 +1,16 @@
+'use client'
+
+import React from "react";
+
+import PublicFooter from '@/components/PublicFooter'
+import PublicHeader from '@/components/PublicHeader'
+
+export default function PublicShell({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex min-h-screen flex-col bg-[linear-gradient(180deg,#ffffff_0%,#f5f8ff_28%,#eef4ff_58%,#ffffff_100%)] text-blue-950 transition-colors dark:bg-[linear-gradient(180deg,#0a1128_0%,#0d1b38_35%,#07101e_100%)] dark:text-slate-100">
+      <PublicHeader />
+      <div className="flex flex-1 flex-col">{children}</div>
+      <PublicFooter />
+    </div>
+  )
+}
@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+afterEach(() => {
+  delete process.env.API_INTERNAL_URL
+  delete process.env.NEXT_PUBLIC_API_URL
+  vi.restoreAllMocks()
+  Reflect.deleteProperty(globalThis, 'fetch')
+  vi.resetModules()
+})
+
+describe('adminFetch', () => {
+  it('requests through the server API base and returns the data envelope', async () => {
+    process.env.API_INTERNAL_URL = 'http://internal-api/api/v1'
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({ data: { companies: [] } }),
+    }))
+    Object.defineProperty(globalThis, 'fetch', { configurable: true, value: fetchMock })
+
+    const { adminFetch } = await import('./api')
+    await expect(adminFetch('/admin/companies', 'admin-token')).resolves.toEqual({ companies: [] })
+
+    expect(fetchMock).toHaveBeenCalledWith('http://internal-api/api/v1/admin/companies', {
+      cache: 'no-store',
+      credentials: 'include',
+    })
+  })
+
+  it('omits authorization when no token is supplied', async () => {
+    delete process.env.API_INTERNAL_URL
+    const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ data: { ok: true } }) }))
+    Object.defineProperty(globalThis, 'fetch', { configurable: true, value: fetchMock })
+
+    const { adminFetch } = await import('./api')
+    await adminFetch('/public')
+
+    expect((fetchMock as any).mock.calls[0]?.[1]).toEqual({ cache: 'no-store', credentials: 'include' })
+  })
+
+  it('throws the API message from failed responses', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: false, json: async () => ({ message: 'Admin only' }) }))
+    Object.defineProperty(globalThis, 'fetch', { configurable: true, value: fetchMock })
+
+    const { adminFetch } = await import('./api')
+    await expect(adminFetch('/admin/menu')).rejects.toThrow('Admin only')
+  })
+})
@@ -0,0 +1,14 @@
+export const ADMIN_API_BASE =
+  typeof window === 'undefined'
+    ? (process.env.API_INTERNAL_URL ?? process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:4000/api/v1')
+    : (process.env.NEXT_PUBLIC_API_URL ?? '/admin/api/v1')
+
+export async function adminFetch<T>(path: string, _token?: string): Promise<T> {
+  const res = await fetch(`${ADMIN_API_BASE}${path}`, {
+    cache: 'no-store',
+    credentials: 'include',
+  })
+  const json = await res.json()
+  if (!res.ok) throw new Error(json?.message ?? 'Request failed')
+  return json.data as T
+}
@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { resolveBrowserAppUrl, resolveServerAppUrl } from './appUrls'
+
+function installWindow(hostname: string, protocol = 'https:') {
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { location: { hostname, protocol } },
+  })
+}
+
+afterEach(() => {
+  Reflect.deleteProperty(globalThis, 'window')
+})
+
+describe('admin app URL resolution', () => {
+  it('keeps server fallback unchanged without a browser window', () => {
+    expect(resolveBrowserAppUrl('http://localhost:3002/admin')).toBe('http://localhost:3002/admin')
+  })
+
+  it('removes trailing slash for localhost browser fallbacks', () => {
+    installWindow('127.0.0.1')
+    expect(resolveBrowserAppUrl('http://localhost:3002/admin/')).toBe('http://localhost:3002/admin')
+  })
+
+  it('rewrites fallback origin to the current browser host in production', () => {
+    installWindow('admin.rentaldrivego.ma')
+    expect(resolveBrowserAppUrl('http://localhost:3002/admin')).toBe('https://admin.rentaldrivego.ma/admin')
+  })
+
+  it('resolves server app URLs from forwarded host and protocol', () => {
+    expect(resolveServerAppUrl('http://localhost:3002/admin', 'admin.example.com', 'https')).toBe('https://admin.example.com:3002/admin')
+  })
+
+  it('falls back when host is missing or the fallback is not parseable', () => {
+    expect(resolveServerAppUrl('http://localhost:3002/admin', null)).toBe('http://localhost:3002/admin')
+    expect(resolveServerAppUrl('/admin', 'admin.example.com')).toBe('/admin')
+  })
+})
@@ -0,0 +1,17 @@
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  if (request.headers.has('x-middleware-subrequest')) {
+    return new NextResponse('Unsupported internal request header', { status: 400 })
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+    '/(api|trpc)(.*)',
+  ],
+}
@@ -0,0 +1,162 @@
+/* RentalDriveGo Phase 16 design tokens.
+ * Kept deliberately identical across the homepage, operator dashboard, and
+ * platform admin so the product behaves like one system rather than three
+ * unrelated Tailwind experiments.
+ */
+:root {
+  --rdg-blue-50: #eff6ff;
+  --rdg-blue-100: #dbeafe;
+  --rdg-blue-200: #bfdbfe;
+  --rdg-blue-500: #2874e8;
+  --rdg-blue-600: #1b5dd8;
+  --rdg-blue-700: #174bb5;
+  --rdg-blue-800: #183d88;
+  --rdg-orange-100: #ffedd5;
+  --rdg-orange-400: #fb923c;
+  --rdg-orange-600: #ea580c;
+  --rdg-orange-700: #c2410c;
+  --rdg-navy-950: #081426;
+  --rdg-navy-900: #0d1b2e;
+  --rdg-navy-850: #11233b;
+  --rdg-navy-800: #162b46;
+  --rdg-gray-25: #fbfdff;
+  --rdg-gray-50: #f7f9fc;
+  --rdg-gray-100: #eef2f7;
+  --rdg-gray-200: #dbe3ed;
+  --rdg-gray-300: #c6d0dc;
+  --rdg-gray-500: #64748b;
+  --rdg-gray-600: #475569;
+  --rdg-gray-700: #334155;
+  --rdg-gray-800: #1e293b;
+  --rdg-gray-900: #0f172a;
+  --rdg-green-100: #dcfce7;
+  --rdg-green-700: #15803d;
+  --rdg-amber-100: #fef3c7;
+  --rdg-amber-800: #92400e;
+  --rdg-red-100: #fee2e2;
+  --rdg-red-700: #b91c1c;
+
+  --rdg-space-1: 4px;
+  --rdg-space-2: 8px;
+  --rdg-space-3: 12px;
+  --rdg-space-4: 16px;
+  --rdg-space-5: 20px;
+  --rdg-space-6: 24px;
+  --rdg-space-8: 32px;
+  --rdg-space-10: 40px;
+  --rdg-space-12: 48px;
+  --rdg-space-16: 64px;
+  --rdg-space-20: 80px;
+  --rdg-space-24: 96px;
+
+  --rdg-radius-sm: 10px;
+  --rdg-radius-md: 16px;
+  --rdg-radius-lg: 24px;
+  --rdg-radius-xl: 32px;
+  --rdg-radius-pill: 999px;
+  --rdg-touch-min: 44px;
+  --rdg-header-size: 76px;
+  --rdg-sidebar-size: 272px;
+  --rdg-container-max: 1440px;
+  --rdg-content-max: 1280px;
+  --rdg-duration-fast: 120ms;
+  --rdg-duration-standard: 160ms;
+  --rdg-duration-overlay: 220ms;
+  --rdg-easing: cubic-bezier(0.2, 0, 0, 1);
+  --rdg-font-latin: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --rdg-font-arabic: "Noto Sans Arabic", Tahoma, Arial, sans-serif;
+
+  --rdg-surface-page: var(--rdg-gray-25);
+  --rdg-surface-primary: #ffffff;
+  --rdg-surface-elevated: #ffffff;
+  --rdg-surface-muted: #f2f6fb;
+  --rdg-surface-strong: #e8f0fa;
+  --rdg-text-primary: #102035;
+  --rdg-text-secondary: #52647a;
+  --rdg-text-subdued: var(--rdg-gray-500);
+  --rdg-text-inverse: #f8fafc;
+  --rdg-border: #d8e2ee;
+  --rdg-border-strong: #bdcad9;
+  --rdg-action-primary: var(--rdg-blue-700);
+  --rdg-action-primary-hover: var(--rdg-blue-800);
+  --rdg-action-conversion: var(--rdg-orange-700);
+  --rdg-action-conversion-hover: #9a3412;
+  --rdg-focus: #f97316;
+  --rdg-soft-blue: #eef5ff;
+  --rdg-soft-orange: #fff7ed;
+  --rdg-overlay: rgba(8, 20, 38, 0.62);
+  --rdg-shadow-color: rgba(8, 20, 38, 0.12);
+  --rdg-shadow-subtle: 0 1px 2px var(--rdg-shadow-color);
+  --rdg-shadow-card: 0 20px 60px var(--rdg-shadow-color);
+  --rdg-shadow-overlay: 0 28px 80px var(--rdg-shadow-color);
+
+  /* Compatibility aliases retained for existing pages. */
+  --primary: var(--rdg-action-primary);
+  --primary-hover: var(--rdg-action-primary-hover);
+  --accent: var(--rdg-action-conversion);
+  --bg-elevated: var(--rdg-surface-elevated);
+  --border-accent: var(--rdg-border);
+  --glass-bg: color-mix(in srgb, var(--rdg-surface-elevated) 90%, transparent);
+  --shadow-card: var(--rdg-shadow-card);
+  --shadow-glow: 0 0 20px color-mix(in srgb, var(--rdg-action-primary) 16%, transparent);
+}
+
+html.dark,
+html[data-theme='dark'] {
+  --rdg-surface-page: var(--rdg-navy-950);
+  --rdg-surface-primary: var(--rdg-navy-900);
+  --rdg-surface-elevated: var(--rdg-navy-850);
+  --rdg-surface-muted: #0b1a2d;
+  --rdg-surface-strong: #172d48;
+  --rdg-text-primary: #eef5ff;
+  --rdg-text-secondary: #adbed2;
+  --rdg-text-subdued: var(--rdg-gray-300);
+  --rdg-text-inverse: var(--rdg-navy-950);
+  --rdg-border: #263c56;
+  --rdg-border-strong: #3a536e;
+  --rdg-action-primary: #76a9ff;
+  --rdg-action-primary-hover: #9bc2ff;
+  --rdg-action-conversion: var(--rdg-orange-400);
+  --rdg-action-conversion-hover: #fdba74;
+  --rdg-focus: var(--rdg-orange-400);
+  --rdg-soft-blue: #10284a;
+  --rdg-soft-orange: #3a2015;
+  --rdg-overlay: rgba(2, 8, 18, 0.76);
+  --rdg-shadow-color: rgba(0, 0, 0, 0.36);
+  color-scheme: dark;
+}
+
+html.light,
+html[data-theme='light'] {
+  color-scheme: light;
+}
+
+html[lang='ar'] body {
+  font-family: var(--rdg-font-arabic);
+  line-height: 1.8;
+}
+
+::selection {
+  background: var(--rdg-blue-200);
+  color: var(--rdg-gray-900);
+}
+
+html.dark ::selection,
+html[data-theme='dark'] ::selection {
+  background: var(--rdg-blue-800);
+  color: var(--rdg-gray-25);
+}
+
+:focus-visible {
+  outline: 3px solid var(--rdg-focus);
+  outline-offset: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
@@ -0,0 +1,17 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  test: {
+    environment: 'node',
+    globals: true,
+    include: ['src/**/*.test.ts'],
+    clearMocks: true,
+    restoreMocks: true,
+  },
+})
@@ -0,0 +1,6 @@
+DATABASE_URL=postgresql://user:replace-with-password@host:5432/db
+REDIS_URL=redis://localhost:6379
+JWT_SECRET=replace-with-64-byte-random-secret
+JWT_EXPIRY=8h
+NODE_ENV=test
+FILE_STORAGE_ROOT=/tmp/rentaldrivego-test-storage
@@ -0,0 +1,73 @@
+{
+  "name": "@rentaldrivego/api",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "predev": "npm run build --workspace @rentaldrivego/types",
+    "dev": "node ../../scripts/run-with-env-file.cjs ../../.env.local ../../node_modules/.bin/ts-node-dev --respawn --transpile-only --ignore-watch ../../packages/types/dist src/index.ts",
+    "prebuild": "npm run build --workspace @rentaldrivego/types",
+    "build": "tsc",
+    "prestart": "npm run build --workspace @rentaldrivego/types",
+    "pretype-check": "npm run build --workspace @rentaldrivego/types",
+    "start": "node dist/index.js",
+    "type-check": "tsc --noEmit",
+    "pretest": "npm run build --workspace @rentaldrivego/types",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pretest:integration": "npm run build --workspace @rentaldrivego/types",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:integration:watch": "vitest --config vitest.integration.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:watch": "vitest --config vitest.e2e.config.ts",
+    "test:api": "vitest run --config vitest.api.config.ts",
+    "test:api:watch": "vitest --config vitest.api.config.ts"
+  },
+  "dependencies": {
+    "@react-pdf/renderer": "^3.4.3",
+    "@rentaldrivego/database": "*",
+    "@rentaldrivego/types": "*",
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "dayjs": "^1.11.11",
+    "express": "^4.19.2",
+    "express-rate-limit": "^8.5.1",
+    "firebase-admin": "^12.1.0",
+    "helmet": "^7.1.0",
+    "ioredis": "^5.3.2",
+    "jsonwebtoken": "^9.0.2",
+    "morgan": "^1.10.0",
+    "multer": "^2.1.1",
+    "node-cron": "^3.0.3",
+    "nodemailer": "^8.0.10",
+    "otplib": "^12.0.1",
+    "qrcode": "^1.5.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "resend": "^3.2.0",
+    "socket.io": "^4.7.5",
+    "swagger-ui-express": "^5.0.1",
+    "twilio": "^5.1.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/morgan": "^1.9.9",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^20.12.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/nodemailer": "^6.4.17",
+    "@types/qrcode": "^1.5.5",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.0",
+    "@types/supertest": "^6.0.2",
+    "@types/swagger-ui-express": "^4.1.8",
+    "supertest": "^7.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}
@@ -0,0 +1,240 @@
+import express from 'express'
+import cors, { type CorsOptions } from 'cors'
+import helmet from 'helmet'
+import morgan from 'morgan'
+import swaggerUi from 'swagger-ui-express'
+import { openApiDocument } from './swagger/openapi'
+import { getPublicStorageRoot } from './lib/storage'
+import { authLimiter, apiLimiter, publicLimiter, adminLimiter } from './middleware/rateLimiter'
+import { requestIdMiddleware } from './middleware/requestId'
+
+// ─── Module routes ────────────────────────────────────────────
+import webhookRouter       from './modules/webhooks/webhook.routes'
+import companyAuthRouter   from './modules/auth/auth.company.routes'
+import employeeAuthRouter  from './modules/auth/auth.employee.routes'
+import accountAuthRouter   from './modules/auth/auth.account.routes'
+import renterAuthRouter    from './modules/auth/auth.renter.routes'
+import teamRouter          from './modules/team/team.routes'
+import offersRouter        from './modules/offers/offer.routes'
+import analyticsRouter     from './modules/analytics/analytics.routes'
+import notificationsRouter from './modules/notifications/notification.routes'
+import adminRouter         from './modules/admin/admin.routes'
+import subscriptionsRouter, {
+  subscriptionPublicRouter,
+  subscriptionWebhookRouter,
+} from './modules/subscriptions/subscription.routes'
+import paymentsRouter      from './modules/payments/payment.routes'
+import customersRouter     from './modules/customers/customer.routes'
+import vehiclesRouter      from './modules/vehicles/vehicle.routes'
+import companiesRouter     from './modules/companies/company.routes'
+import reservationsRouter  from './modules/reservations/reservation.routes'
+import marketplaceRouter   from './modules/marketplace/marketplace.routes'
+import siteRouter          from './modules/site/site.routes'
+import reviewsRouter       from './modules/reviews/review.routes'
+import complaintsRouter    from './modules/complaints/complaint.routes'
+import licenseValidationRouter from './modules/licenses/license.validation.routes'
+
+// ─── Centralized error handling ───────────────────────────────
+import { errorMiddleware } from './http/errors/errorMiddleware'
+
+const v1 = '/api/v1'
+
+const defaultCorsOrigins = [
+  'http://localhost:3000',
+  'http://localhost:3001',
+  'http://localhost:3002',
+  'http://localhost:4000',
+  'http://127.0.0.1:3000',
+  'http://127.0.0.1:3001',
+  'http://127.0.0.1:3002',
+  'http://127.0.0.1:4000',
+]
+
+export const corsOrigins = process.env.CORS_ORIGINS
+  ? process.env.CORS_ORIGINS.split(',').map((o) => o.trim()).filter(Boolean)
+  : defaultCorsOrigins
+
+function isAllowedLocalDevOrigin(origin: string) {
+  if (process.env.NODE_ENV === 'production') return false
+
+  try {
+    const url = new URL(origin)
+    return (
+      url.protocol === 'http:' &&
+      ['localhost', '127.0.0.1'].includes(url.hostname) &&
+      ['3000', '3001', '3002', '4000'].includes(url.port)
+    )
+  } catch {
+    return false
+  }
+}
+
+export function isCorsOriginAllowed(origin: string | undefined) {
+  if (!origin) return true
+  return corsOrigins.includes(origin) || isAllowedLocalDevOrigin(origin)
+}
+
+export const corsOptions: CorsOptions = {
+  origin(origin, callback) {
+    callback(null, isCorsOriginAllowed(origin))
+  },
+  credentials: true,
+}
+
+const routeDocs = [
+  { method: 'GET',  path: '/health',                         description: 'Health check' },
+  { method: 'GET',  path: `${v1}/docs`,                      description: 'Machine-readable API index' },
+  { method: 'GET',  path: `${v1}/auth/renter/me`,            description: 'Current renter profile' },
+  { method: 'GET',  path: `${v1}/vehicles`,                  description: 'List company vehicles' },
+  { method: 'POST', path: `${v1}/vehicles`,                  description: 'Create vehicle' },
+  { method: 'GET',  path: `${v1}/reservations`,              description: 'List reservations' },
+  { method: 'POST', path: `${v1}/reservations`,              description: 'Create reservation' },
+  { method: 'GET',  path: `${v1}/customers`,                 description: 'List customers' },
+  { method: 'POST', path: `${v1}/customers`,                 description: 'Create customer' },
+  { method: 'GET',  path: `${v1}/offers`,                    description: 'List offers' },
+  { method: 'GET',  path: `${v1}/analytics/dashboard`,       description: 'Dashboard analytics' },
+  { method: 'GET',  path: `${v1}/analytics/report`,          description: 'Analytics report' },
+  { method: 'GET',  path: `${v1}/notifications/company`,     description: 'Company notifications' },
+  { method: 'GET',  path: `${v1}/marketplace/cities`,        description: 'Marketplace cities' },
+  { method: 'GET',  path: `${v1}/marketplace/search`,        description: 'Marketplace search' },
+  { method: 'GET',  path: `${v1}/site/:slug/brand`,          description: 'Public site brand config' },
+  { method: 'GET',  path: `${v1}/companies/me`,              description: 'Current company profile' },
+  { method: 'GET',  path: `${v1}/subscriptions/plans`,       description: 'Subscription plans' },
+  { method: 'GET',  path: `${v1}/subscriptions/features`,    description: 'Subscription plan features' },
+  { method: 'POST', path: `${v1}/admin/auth/login`,          description: 'Admin login' },
+]
+
+export function createApp() {
+  const app = express()
+  const corsMiddleware = cors(corsOptions)
+
+  if (process.env.NODE_ENV === 'production') {
+    app.set('trust proxy', 1)
+  }
+
+  app.use(requestIdMiddleware)
+
+  app.use((req, res, next) => {
+    if (req.headers['x-middleware-subrequest']) {
+      return res.status(400).json({ error: 'bad_request', message: 'Unsupported internal request header', statusCode: 400 })
+    }
+    next()
+  })
+
+  app.use(corsMiddleware)
+
+  // Customer identity documents must never be anonymously retrievable from the
+  // public storage mount, even if an older raw storage URL leaks.
+  app.use('/storage/companies/:companyId/customers/:customerId', (_req, res) => {
+    res.status(404).end()
+  })
+
+  // Public storage assets (logos, vehicle photos, etc.) must be loadable cross-origin
+  // by the browser. Without this header, helmet's default CORP: same-origin reaches
+  // 404 responses (when express.static calls next() on a miss) and the browser blocks
+  // the response even for broken-image cases, producing ERR_BLOCKED_BY_RESPONSE.
+  app.use('/storage', (_req, res, next) => {
+    res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin')
+    next()
+  })
+
+  // Serve only explicitly public uploaded assets. Private documents are resolved
+  // through authenticated API routes such as /customers/:id/license-image.
+  app.use('/storage', express.static(getPublicStorageRoot()))
+
+  // Swagger UI — mounted before helmet so its assets are not blocked by CSP
+  app.use('/docs', swaggerUi.serve, swaggerUi.setup(openApiDocument, { customSiteTitle: 'RentalDriveGo API Docs' }))
+  app.get('/api/v1/openapi.json', (_req, res) => res.json(openApiDocument))
+
+  // Webhooks must use raw body BEFORE express.json(); signature verification
+  // must never reconstruct the payload with JSON.stringify(req.body).
+  app.use(`${v1}/webhooks`, express.raw({ type: 'application/json' }), webhookRouter)
+  app.use(`${v1}/payments/webhooks`, express.raw({ type: 'application/json' }))
+  app.use(`${v1}/subscriptions/webhooks`, express.raw({ type: 'application/json' }))
+
+  // Let /storage responses manage CORP explicitly so missing files still return
+  // a normal cross-origin 404 instead of being blocked by Helmet's default
+  // same-origin policy. Keep CSP explicit instead of letting browser security
+  // drift into wishful thinking with headers.
+  app.use(helmet({
+    crossOriginResourcePolicy: false,
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        baseUri: ["'self'"],
+        frameAncestors: ["'none'"],
+        formAction: ["'self'"],
+        objectSrc: ["'none'"],
+        scriptSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        imgSrc: ["'self'", 'data:', 'blob:', 'https:'],
+        connectSrc: ["'self'", 'https:', 'wss:'],
+        upgradeInsecureRequests: process.env.NODE_ENV === 'production' ? [] : null,
+      },
+    },
+    referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+    frameguard: { action: 'deny' },
+  }))
+  if (process.env.NODE_ENV !== 'test') app.use(morgan('combined'))
+  app.use(express.json({ limit: '10mb' }))
+
+  // ─── API Routes ─────────────────────────────────────────────
+  app.use(`${v1}/auth/account`,   authLimiter, accountAuthRouter)
+  app.use(`${v1}/auth/renter`,    authLimiter, renterAuthRouter)
+  app.use(`${v1}/auth/company`,   authLimiter, companyAuthRouter)
+  app.use(`${v1}/auth/employee`,  authLimiter, employeeAuthRouter)
+
+  app.use(`${v1}/admin/auth`,     authLimiter)
+  app.use(`${v1}/admin`,          adminLimiter, adminRouter)
+
+  app.use(`${v1}/marketplace`,    publicLimiter, marketplaceRouter)
+  app.use(`${v1}/site`,           publicLimiter, siteRouter)
+  app.use(`${v1}/subscriptions`,  subscriptionPublicRouter)
+  app.use(`${v1}/subscriptions`,  subscriptionWebhookRouter)
+
+  app.use(`${v1}/vehicles`,       apiLimiter, vehiclesRouter)
+  app.use(`${v1}/reservations`,   apiLimiter, reservationsRouter)
+  app.use(`${v1}/team`,           apiLimiter, teamRouter)
+  app.use(`${v1}/customers`,      apiLimiter, customersRouter)
+  app.use(`${v1}/offers`,         apiLimiter, offersRouter)
+  app.use(`${v1}/analytics`,      apiLimiter, analyticsRouter)
+  app.use(`${v1}/notifications`,  apiLimiter, notificationsRouter)
+  app.use(`${v1}/companies`,      apiLimiter, companiesRouter)
+  app.use(`${v1}/subscriptions`,  apiLimiter, subscriptionsRouter)
+  app.use(`${v1}/payments`,       apiLimiter, paymentsRouter)
+  app.use(`${v1}/reviews`,        apiLimiter, reviewsRouter)
+  app.use(`${v1}/complaints`,     apiLimiter, complaintsRouter)
+  app.use(`${v1}/licenses`,       publicLimiter, licenseValidationRouter)
+
+  // ─── Health / Docs ──────────────────────────────────────────
+  app.get(v1, (_req, res) => {
+    res.json({
+      name: 'rentaldrivego-api',
+      version: '1.0.0',
+      baseUrl: v1,
+      health: '/health',
+      docs: `${v1}/docs`,
+      openApi: `${v1}/openapi.json`,
+    })
+  })
+
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', version: '1.0.0', timestamp: new Date().toISOString() })
+  })
+
+  app.get(`${v1}/docs`, (_req, res) => {
+    res.json({
+      name: 'rentaldrivego-api',
+      version: '1.0.0',
+      baseUrl: v1,
+      routes: routeDocs,
+      swaggerUi: '/docs',
+      openApi: '/api/v1/openapi.json',
+    })
+  })
+
+  // ─── Error handler ──────────────────────────────────────────
+  app.use(errorMiddleware)
+
+  return app
+}
@@ -0,0 +1,331 @@
+{
+  "marketplaceHomepage": {
+    "en": {
+      "sections": [
+        "hero",
+        "surface",
+        "pillars",
+        "audiences",
+        "features",
+        "howitworks",
+        "steps",
+        "testimonials",
+        "closing"
+      ],
+      "heroKicker": "RentalDriveGo",
+      "heroTitle": "Marketplace discovery with a sharper front door.",
+      "heroBody": "Rental companies run private operations, renters browse a shared marketplace, and every booking ends on the company’s own branded checkout.",
+      "startTrial": "Start free trial",
+      "exploreVehicles": "Explore vehicles",
+      "surfaceLabel": "Marketplace surface",
+      "surfaceTitle": "Designed for two audiences at once.",
+      "surfaceBody": "Operators need control, renters need confidence. The marketplace should show both without feeling like a template.",
+      "liveLabel": "Live network",
+      "trustedFleets": "Trusted fleets",
+      "brandedFlows": "Branded booking flows",
+      "multiTenant": "Multi-tenant operations",
+      "companyKicker": "Operator workflow",
+      "companyTitle": "Manage inventory, offers, billing, and staff from one control layer.",
+      "companyBody": "Publish inventory once, decide what appears publicly, and keep contracts, payments, and reporting isolated per company.",
+      "renterKicker": "Renter experience",
+      "renterTitle": "Let renters compare quickly, then hand them off to the right company site.",
+      "renterBody": "The marketplace works as a discovery engine, not a dead-end aggregator. Search here, reserve there, and pay direct.",
+      "pillars": [
+        {
+          "title": "Unified publishing",
+          "body": "Vehicle photos, pricing, and offers flow from one admin workflow into marketplace discovery and branded booking pages."
+        },
+        {
+          "title": "Qualified discovery",
+          "body": "Featured offers, location-aware browsing, and company reputation signals help renters narrow options fast."
+        },
+        {
+          "title": "Direct revenue path",
+          "body": "Bookings move into the company’s own payment flow, so customer ownership and cash collection stay with the business."
+        }
+      ],
+      "metrics": [
+        {
+          "value": "01",
+          "label": "Shared marketplace visibility"
+        },
+        {
+          "value": "02",
+          "label": "Direct company checkout"
+        },
+        {
+          "value": "03",
+          "label": "Company-owned payments"
+        }
+      ],
+      "featureLabel": "What the product covers",
+      "features": [
+        "Fleet management with multi-photo uploads",
+        "Marketplace offers and redirect booking flow",
+        "Branded public booking site per company",
+        "Customer CRM, analytics, and billing controls"
+      ],
+      "howitworksKicker": "GETTING STARTED",
+      "howitworksTitle": "How It Works",
+      "howitworksSteps": [
+        {
+          "number": "1",
+          "title": "Create Account",
+          "description": "Sign up for your company workspace and choose your pricing plan for the 90-day free trial."
+        },
+        {
+          "number": "2",
+          "title": "Add Your Fleet",
+          "description": "Upload vehicle photos, set prices, and create offers visible on the marketplace."
+        },
+        {
+          "number": "3",
+          "title": "Start Selling",
+          "description": "Renters discover your fleet, and bookings flow directly to your branded checkout."
+        }
+      ],
+      "stepsTitle": "How companies launch",
+      "steps": [
+        {
+          "step": "1",
+          "title": "Create your company workspace",
+          "body": "Pick a plan, launch your 90-day trial, and verify the owner account."
+        },
+        {
+          "step": "2",
+          "title": "Publish vehicles and offers",
+          "body": "Upload photos once and control what appears on the marketplace and branded site."
+        },
+        {
+          "step": "3",
+          "title": "Accept bookings on your own site",
+          "body": "Renters discover your fleet on RentalDriveGo, then pay you directly on your branded booking flow."
+        }
+      ],
+      "stepLabel": "Step",
+      "readyKicker": "Ready to launch",
+      "readyTitle": "The marketplace homepage should explain the product in seconds.",
+      "readyBody": "Use the marketplace to attract demand, then move renters into a branded experience that keeps pricing, payments, and trust tied to your company.",
+      "viewPricing": "View pricing",
+      "createWorkspace": "Create workspace"
+    },
+    "fr": {
+      "sections": [
+        "hero",
+        "surface",
+        "pillars",
+        "audiences",
+        "features",
+        "howitworks",
+        "steps",
+        "testimonials",
+        "closing"
+      ],
+      "heroKicker": "RentalDriveGo",
+      "heroTitle": "Une vitrine marketplace plus claire et plus percutante.",
+      "heroBody": "Les entreprises de location gèrent leurs opérations en privé, les clients parcourent une marketplace commune et chaque réservation se finalise sur le parcours de paiement aux couleurs de l'entreprise.",
+      "startTrial": "Commencer l’essai gratuit",
+      "exploreVehicles": "Explorer les véhicules",
+      "surfaceLabel": "Vitrine marketplace",
+      "surfaceTitle": "Pensée pour deux audiences à la fois.",
+      "surfaceBody": "Les opérateurs veulent du contrôle, les clients veulent de la confiance. La marketplace doit montrer les deux sans ressembler à un modèle générique.",
+      "liveLabel": "Réseau actif",
+      "trustedFleets": "Flottes fiables",
+      "brandedFlows": "Parcours de marque",
+      "multiTenant": "Opérations multi-tenant",
+      "companyKicker": "Flux opérateur",
+      "companyTitle": "Pilotez l’inventaire, les offres, la facturation et l’équipe depuis un seul centre de contrôle.",
+      "companyBody": "Publiez une seule fois, choisissez ce qui apparaît publiquement, et gardez contrats, paiements et rapports isolés par entreprise.",
+      "renterKicker": "Expérience client",
+      "renterTitle": "Laissez les clients comparer rapidement, puis redirigez-les vers le bon site d’entreprise.",
+      "renterBody": "La marketplace sert de moteur de découverte, pas d’agrégateur sans suite. Recherche ici, réservation là-bas, paiement direct.",
+      "pillars": [
+        {
+          "title": "Publication unifiée",
+          "body": "Les photos, tarifs et offres circulent depuis un seul flux d’administration vers la découverte marketplace et les pages de réservation de marque."
+        },
+        {
+          "title": "Découverte qualifiée",
+          "body": "Offres mises en avant, navigation par localisation et signaux de réputation aident les clients à filtrer rapidement."
+        },
+        {
+          "title": "Revenus en direct",
+          "body": "Les réservations basculent vers le paiement propre à l’entreprise afin de préserver la relation client et l’encaissement."
+        }
+      ],
+      "metrics": [
+        {
+          "value": "01",
+          "label": "Visibilité marketplace partagée"
+        },
+        {
+          "value": "02",
+          "label": "Paiement direct entreprise"
+        },
+        {
+          "value": "03",
+          "label": "Paiements gérés par l’entreprise"
+        }
+      ],
+      "featureLabel": "Ce que couvre le produit",
+      "features": [
+        "Gestion de flotte avec téléversement de plusieurs photos",
+        "Offres marketplace et redirection vers la réservation",
+        "Site public de réservation par entreprise",
+         "CRM client, analytics et contrôle de facturation"
+       ],
+       "howitworksKicker": "MISE EN ROUTE",
+       "howitworksTitle": "Comment ça marche",
+       "howitworksSteps": [
+         {
+           "number": "1",
+           "title": "Créer un compte",
+           "description": "Inscrivez-vous à votre espace entreprise et choisissez votre forfait pour l'essai gratuit de 90 jours."
+         },
+         {
+           "number": "2",
+           "title": "Ajouter votre flotte",
+           "description": "Téléversez les photos des véhicules, fixez les tarifs et créez des offres visibles sur la marketplace."
+         },
+         {
+           "number": "3",
+           "title": "Commencer à vendre",
+           "description": "Les clients découvrent votre flotte et les réservations arrivent directement à votre paiement de marque."
+         }
+       ],
+       "stepsTitle": "Comment les entreprises démarrent",
+      "steps": [
+        {
+          "step": "1",
+          "title": "Créez votre espace entreprise",
+          "body": "Choisissez un plan, lancez votre essai de 90 jours et vérifiez le compte propriétaire."
+        },
+        {
+          "step": "2",
+          "title": "Publiez véhicules et offres",
+          "body": "Téléversez une seule fois et contrôlez ce qui apparaît sur la marketplace et le site de marque."
+        },
+        {
+          "step": "3",
+          "title": "Acceptez les réservations sur votre site",
+          "body": "Les clients découvrent votre flotte sur RentalDriveGo puis paient directement via votre parcours de réservation."
+        }
+      ],
+      "stepLabel": "Étape",
+      "readyKicker": "Prêt à démarrer",
+      "readyTitle": "La page d’accueil marketplace doit présenter le produit en quelques secondes.",
+      "readyBody": "Utilisez la marketplace pour capter la demande, puis orientez les clients vers une expérience de marque où les prix, les paiements et la confiance restent attachés à votre entreprise.",
+      "viewPricing": "Voir les tarifs",
+      "createWorkspace": "Créer l’espace"
+    },
+    "ar": {
+      "sections": [
+        "hero",
+        "surface",
+        "pillars",
+        "audiences",
+        "features",
+        "howitworks",
+        "steps",
+        "testimonials",
+        "closing"
+      ],
+      "heroKicker": "RentalDriveGo",
+      "heroTitle": "واجهة سوق أكثر وضوحاً وتأثيراً.",
+      "heroBody": "شركات التأجير تدير عملياتها بشكل خاص، والمستأجرون يتصفحون سوقاً مشتركاً، وكل حجز ينتهي في صفحة دفع تحمل هوية الشركة ذاتها.",
+      "startTrial": "ابدأ التجربة المجانية",
+      "exploreVehicles": "استكشف السيارات",
+      "surfaceLabel": "واجهة السوق",
+      "surfaceTitle": "مصممة لجمهورين في الوقت نفسه.",
+      "surfaceBody": "المشغلون يريدون التحكم، والمستأجرون يريدون الثقة. يجب أن تُظهر المنصة الأمرين معاً من دون أن تبدو كقالب عادي.",
+      "liveLabel": "شبكة نشطة",
+      "trustedFleets": "أساطيل موثوقة",
+      "brandedFlows": "مسارات حجز مخصصة",
+      "multiTenant": "عمليات متعددة الشركات",
+      "companyKicker": "سير عمل المشغل",
+      "companyTitle": "تحكم في المخزون والعروض والفوترة والفريق من طبقة تشغيل واحدة.",
+      "companyBody": "انشر المخزون مرة واحدة، وحدد ما يظهر للعامة، واحتفظ بالعقود والمدفوعات والتقارير معزولة لكل شركة.",
+      "renterKicker": "تجربة المستأجر",
+      "renterTitle": "دع المستأجرين يقارنون بسرعة ثم وجّههم إلى موقع الشركة المناسب.",
+      "renterBody": "هذه المنصة محرك لاكتشاف الخيارات، وليست مُجمِّعاً بلا مسار واضح. ابحث هنا، احجز هناك، وادفع مباشرة للشركة.",
+      "pillars": [
+        {
+          "title": "نشر موحد",
+          "body": "صور السيارات والأسعار والعروض تنتقل من سير إدارة واحد إلى السوق وصفحات الحجز ذات الهوية الخاصة."
+        },
+        {
+          "title": "اكتشاف مؤهل",
+          "body": "تساعد العروض المميزة، والتصفح حسب الموقع، وإشارات السمعة المستأجرين على تحديد خياراتهم بسرعة."
+        },
+        {
+          "title": "مسار إيراد مباشر",
+          "body": "تنتقل الحجوزات إلى صفحة الدفع الخاصة بالشركة حتى تبقى علاقة العميل والتحصيل المالي بيد الشركة نفسها."
+        }
+      ],
+      "metrics": [
+        {
+          "value": "01",
+          "label": "ظهور مشترك في السوق"
+        },
+        {
+          "value": "02",
+          "label": "دفع مباشر للشركة"
+        },
+        {
+          "value": "03",
+          "label": "مدفوعات مملوكة للشركة"
+        }
+      ],
+      "featureLabel": "ما الذي يقدمه المنتج",
+      "features": [
+        "إدارة الأسطول مع رفع عدة صور",
+        "عروض السوق والتحويل إلى مسار الحجز",
+        "موقع حجز عام مخصص لكل شركة",
+         "إدارة العملاء والتحليلات والفوترة"
+       ],
+       "howitworksKicker": "البدء",
+       "howitworksTitle": "كيف يعمل",
+       "howitworksSteps": [
+         {
+           "number": "1",
+           "title": "إنشاء حساب",
+           "description": "قم بالتسجيل للحصول على مساحة عمل شركتك واختر خطتك للتجربة المجانية لمدة 90 يوماً."
+         },
+         {
+           "number": "2",
+           "title": "أضف أسطولك",
+           "description": "قم برفع صور السيارات، وحدد الأسعار، وأنشئ عروضاً مرئية في السوق."
+         },
+         {
+           "number": "3",
+           "title": "ابدأ البيع",
+           "description": "يكتشف المستأجرون أسطولك وتأتي الحجوزات مباشرة إلى دفعتك المخصصة."
+         }
+       ],
+       "stepsTitle": "كيف تبدأ الشركات",
+      "steps": [
+        {
+          "step": "1",
+          "title": "أنشئ مساحة عمل شركتك",
+          "body": "اختر الخطة وابدأ تجربتك لمدة 14 يوماً ثم فعّل حساب المالك."
+        },
+        {
+          "step": "2",
+          "title": "انشر السيارات والعروض",
+          "body": "ارفع الصور مرة واحدة وتحكم فيما يظهر في السوق وفي الموقع المخصص."
+        },
+        {
+          "step": "3",
+          "title": "استقبل الحجوزات على موقعك",
+          "body": "يكتشف المستأجرون أسطولك على RentalDriveGo ثم يدفعون مباشرة عبر مسار الحجز الخاص بك."
+        }
+      ],
+      "stepLabel": "الخطوة",
+      "readyKicker": "جاهز للانطلاق",
+      "readyTitle": "يجب أن تشرح الصفحة الرئيسية قيمة المنصة خلال ثوانٍ.",
+      "readyBody": "استخدم السوق لجذب الطلب، ثم انقل المستأجرين إلى تجربة تحمل هوية شركتك، بحيث تبقى الأسعار والمدفوعات والثقة مرتبطة بنشاطك.",
+      "viewPricing": "عرض الأسعار",
+      "createWorkspace": "إنشاء المساحة"
+    }
+  }
+}
@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Response } from 'express'
+import { z } from 'zod'
+import { AppError, ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError } from './index'
+import { errorMiddleware } from './errorMiddleware'
+
+function createResponseStub() {
+  const res = {
+    status: vi.fn(),
+    json: vi.fn(),
+  }
+
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+
+  return res as unknown as Response & typeof res
+}
+
+function handle(error: unknown) {
+  const res = createResponseStub()
+  errorMiddleware(error, {} as any, res, vi.fn())
+  return res
+}
+
+describe('AppError subclasses', () => {
+  it.each([
+    [new ValidationError('Bad payload'), 400, 'validation_error'],
+    [new UnauthorizedError(), 401, 'unauthorized'],
+    [new ForbiddenError(), 403, 'forbidden'],
+    [new NotFoundError(), 404, 'not_found'],
+    [new ConflictError(), 409, 'conflict'],
+  ])('sets stable status and error code for %s', (error, statusCode, code) => {
+    expect(error).toBeInstanceOf(AppError)
+    expect(error.statusCode).toBe(statusCode)
+    expect(error.error).toBe(code)
+  })
+})
+
+describe('errorMiddleware', () => {
+  it('normalizes Zod errors into validation responses', () => {
+    const result = z.object({ email: z.string().email() }).safeParse({ email: 'not-an-email' })
+    expect(result.success).toBe(false)
+
+    const res = handle(result.success ? new Error('unexpected') : result.error)
+
+    expect(res.status).toHaveBeenCalledWith(400)
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      error: 'validation_error',
+      message: 'Invalid request body',
+      statusCode: 400,
+      issues: expect.any(Array),
+    }))
+  })
+
+  it('normalizes Prisma not found errors', () => {
+    const res = handle({ code: 'P2025' })
+
+    expect(res.status).toHaveBeenCalledWith(404)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'not_found',
+      message: 'Resource not found',
+      statusCode: 404,
+    })
+  })
+
+  it('normalizes Prisma unique constraint errors', () => {
+    const res = handle({ code: 'P2002' })
+
+    expect(res.status).toHaveBeenCalledWith(409)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'conflict',
+      message: 'A resource with this value already exists',
+      statusCode: 409,
+    })
+  })
+
+  it('preserves AppError metadata in the response body', () => {
+    const res = handle(new AppError('Plan required', 402, 'payment_required', { requiredPlan: 'PRO' }))
+
+    expect(res.status).toHaveBeenCalledWith(402)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'payment_required',
+      message: 'Plan required',
+      statusCode: 402,
+      requiredPlan: 'PRO',
+    })
+  })
+
+  it('falls back to a 500 internal error response', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+
+    const res = handle(new Error('boom'))
+
+    expect(res.status).toHaveBeenCalledWith(500)
+    expect(res.json).toHaveBeenCalledWith({ error: 'internal_error', message: 'Internal server error', statusCode: 500, requestId: undefined })
+
+    spy.mockRestore()
+  })
+})
@@ -0,0 +1,48 @@
+import { Request, Response, NextFunction } from 'express'
+import { AppError } from './index'
+
+function withRequestId(req: Request, payload: Record<string, unknown>) {
+  return { ...payload, requestId: req.requestId }
+}
+
+export function errorMiddleware(err: any, req: Request, res: Response, _next: NextFunction) {
+  if (err.name === 'ZodError') {
+    return res.status(400).json(withRequestId(req, {
+      error: 'validation_error',
+      message: 'Invalid request body',
+      issues: err.issues,
+      statusCode: 400,
+    }))
+  }
+
+  if (err.code === 'P2025') {
+    return res.status(404).json(withRequestId(req, { error: 'not_found', message: 'Resource not found', statusCode: 404 }))
+  }
+
+  if (err.code === 'P2002') {
+    return res.status(409).json(withRequestId(req, { error: 'conflict', message: 'A resource with this value already exists', statusCode: 409 }))
+  }
+
+  if (err instanceof AppError) {
+    if (err.statusCode >= 500) console.error('[API Error]', { requestId: req.requestId, err })
+    return res.status(err.statusCode).json(withRequestId(req, {
+      error: err.error,
+      message: err.statusCode >= 500 ? 'Internal server error' : err.message,
+      statusCode: err.statusCode,
+      ...(err.statusCode >= 500 ? {} : err.data),
+    }))
+  }
+
+  const statusCode = typeof err.statusCode === 'number' ? err.statusCode : 500
+  const safeStatusCode = statusCode >= 400 && statusCode < 600 ? statusCode : 500
+
+  if (safeStatusCode >= 500) {
+    console.error('[API Error]', { requestId: req.requestId, err })
+  }
+
+  res.status(safeStatusCode).json(withRequestId(req, {
+    error: safeStatusCode >= 500 ? 'internal_error' : (err.code ?? 'request_error'),
+    message: safeStatusCode >= 500 ? 'Internal server error' : (err.message ?? 'Request failed'),
+    statusCode: safeStatusCode,
+  }))
+}
@@ -0,0 +1,43 @@
+export class AppError extends Error {
+  readonly statusCode: number
+  readonly error: string
+  readonly data?: Record<string, unknown>
+
+  constructor(message: string, statusCode: number, error: string, data?: Record<string, unknown>) {
+    super(message)
+    this.statusCode = statusCode
+    this.error = error
+    this.data = data
+    this.name = this.constructor.name
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message = 'Validation error') {
+    super(message, 400, 'validation_error')
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Resource not found') {
+    super(message, 404, 'not_found')
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'A resource with this value already exists') {
+    super(message, 409, 'conflict')
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 403, 'forbidden')
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 401, 'unauthorized')
+  }
+}
@@ -0,0 +1,13 @@
+import { Response } from 'express'
+
+export function ok<T>(res: Response, data: T): void {
+  res.json({ data })
+}
+
+export function created<T>(res: Response, data: T): void {
+  res.status(201).json({ data })
+}
+
+export function noContent(res: Response): void {
+  res.status(204).end()
+}
@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Response } from 'express'
+import { created, noContent, ok } from './index'
+
+function createResponseStub() {
+  const res = {
+    status: vi.fn(),
+    json: vi.fn(),
+    end: vi.fn(),
+  }
+
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  res.end.mockReturnValue(res)
+
+  return res as unknown as Response & typeof res
+}
+
+describe('http/respond helpers', () => {
+  it('ok responds with the expected data envelope', () => {
+    const res = createResponseStub()
+    const payload = { id: 'vehicle_1', name: 'Dacia Logan' }
+
+    ok(res, payload)
+
+    expect(res.status).not.toHaveBeenCalled()
+    expect(res.json).toHaveBeenCalledWith({ data: payload })
+  })
+
+  it('created responds with status 201 and the expected data envelope', () => {
+    const res = createResponseStub()
+    const payload = { id: 'reservation_1' }
+
+    created(res, payload)
+
+    expect(res.status).toHaveBeenCalledWith(201)
+    expect(res.json).toHaveBeenCalledWith({ data: payload })
+  })
+
+  it('noContent responds with status 204 and no body', () => {
+    const res = createResponseStub()
+
+    noContent(res)
+
+    expect(res.status).toHaveBeenCalledWith(204)
+    expect(res.end).toHaveBeenCalledWith()
+    expect(res.json).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,83 @@
+import path from 'path'
+import multer from 'multer'
+import { ValidationError } from '../errors'
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10 MB
+const ALLOWED_IMAGE_TYPES = new Map<string, string[]>([
+  ['image/jpeg', ['.jpg', '.jpeg']],
+  ['image/png', ['.png']],
+  ['image/webp', ['.webp']],
+  ['image/gif', ['.gif']],
+])
+
+/**
+ * Shared multer instance used by all upload endpoints.
+ * Files are kept in memory so services receive a Buffer — no temp-file cleanup needed.
+ */
+export const imageUpload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: MAX_FILE_SIZE, files: 20 },
+})
+
+type DetectedFile = { mime: string; ext: string }
+
+export function detectImageType(buffer: Buffer): DetectedFile | null {
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return { mime: 'image/jpeg', ext: '.jpg' }
+  }
+
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47 &&
+    buffer[4] === 0x0d && buffer[5] === 0x0a && buffer[6] === 0x1a && buffer[7] === 0x0a
+  ) {
+    return { mime: 'image/png', ext: '.png' }
+  }
+
+  if (buffer.length >= 12 && buffer.subarray(0, 4).toString('ascii') === 'RIFF' && buffer.subarray(8, 12).toString('ascii') === 'WEBP') {
+    return { mime: 'image/webp', ext: '.webp' }
+  }
+
+  if (buffer.length >= 6) {
+    const sig = buffer.subarray(0, 6).toString('ascii')
+    if (sig === 'GIF87a' || sig === 'GIF89a') return { mime: 'image/gif', ext: '.gif' }
+  }
+
+  return null
+}
+
+function assertSafeImageContent(file: Express.Multer.File) {
+  const detected = detectImageType(file.buffer)
+  if (!detected || !ALLOWED_IMAGE_TYPES.has(detected.mime)) {
+    throw new ValidationError(`Unsupported or spoofed image file: ${file.originalname}`)
+  }
+
+  if (file.mimetype !== detected.mime) {
+    throw new ValidationError(`MIME type does not match file content for "${file.originalname}"`)
+  }
+
+  const ext = path.extname(file.originalname).toLowerCase()
+  const allowedExtensions = ALLOWED_IMAGE_TYPES.get(detected.mime) ?? []
+  if (ext && !allowedExtensions.includes(ext)) {
+    throw new ValidationError(`File extension does not match file content for "${file.originalname}"`)
+  }
+}
+
+/**
+ * Asserts that a file was provided and is an image by content, not by client claims.
+ */
+export function assertImageFile(
+  file: Express.Multer.File | undefined,
+  fieldLabel = 'file',
+): asserts file is Express.Multer.File {
+  if (!file) throw new ValidationError(`A ${fieldLabel} is required`)
+  assertSafeImageContent(file)
+}
+
+/**
+ * Asserts that at least one file was provided and all files are image content.
+ */
+export function assertImageFiles(files: Express.Multer.File[], fieldLabel = 'photos'): void {
+  if (!files || files.length === 0) throw new ValidationError(`At least one ${fieldLabel} file is required`)
+  for (const file of files) assertSafeImageContent(file)
+}
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { ValidationError } from '../errors'
+import { assertImageFile, assertImageFiles } from './index'
+
+const file = (overrides: Partial<Express.Multer.File> = {}) => ({
+  fieldname: 'file',
+  originalname: 'photo.jpg',
+  encoding: '7bit',
+  mimetype: 'image/jpeg',
+  size: 123,
+  buffer: Buffer.from([0xff, 0xd8, 0xff, 0xdb]),
+  stream: undefined as any,
+  destination: '',
+  filename: '',
+  path: '',
+  ...overrides,
+})
+
+describe('upload assertions', () => {
+  it('accepts a single image file and narrows the route input', () => {
+    expect(() => assertImageFile(file())).not.toThrow()
+  })
+
+  it('rejects missing single file uploads with a field-specific error', () => {
+    expect(() => assertImageFile(undefined, 'license image')).toThrow(ValidationError)
+    expect(() => assertImageFile(undefined, 'license image')).toThrow('A license image is required')
+  })
+
+  it('rejects non-image single file uploads', () => {
+    expect(() => assertImageFile(file({ mimetype: 'application/pdf', originalname: 'license.pdf' }))).toThrow('MIME type does not match file content')
+  })
+
+  it('accepts multiple image files and rejects empty or mixed batches', () => {
+    expect(() => assertImageFiles([file({ originalname: 'front.png', mimetype: 'image/png', buffer: Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) })])).not.toThrow()
+    expect(() => assertImageFiles([], 'inspection photos')).toThrow('At least one inspection photos file is required')
+    expect(() => assertImageFiles([
+      file({ originalname: 'front.png', mimetype: 'image/png', buffer: Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) }),
+      file({ originalname: 'report.pdf', mimetype: 'application/pdf', buffer: Buffer.from('%PDF') }),
+    ])).toThrow('Unsupported or spoofed image file: report.pdf')
+  })
+})
@@ -0,0 +1,14 @@
+import type { Request } from 'express'
+import type { ZodTypeAny, output } from 'zod'
+
+export function parseBody<TSchema extends ZodTypeAny>(schema: TSchema, req: Request): output<TSchema> {
+  return schema.parse(req.body)
+}
+
+export function parseQuery<TSchema extends ZodTypeAny>(schema: TSchema, req: Request): output<TSchema> {
+  return schema.parse(req.query)
+}
+
+export function parseParams<TSchema extends ZodTypeAny>(schema: TSchema, req: Request): output<TSchema> {
+  return schema.parse(req.params)
+}
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import type { Request } from 'express'
+import { z } from 'zod'
+import { parseBody, parseParams, parseQuery } from './index'
+
+describe('http/validate parsers', () => {
+  it('parseBody returns typed and coerced request body values', () => {
+    const schema = z.object({ seats: z.coerce.number().int().min(1), brand: z.string().min(1) })
+    const req = { body: { seats: '5', brand: 'Toyota' } } as Request
+
+    expect(parseBody(schema, req)).toEqual({ seats: 5, brand: 'Toyota' })
+  })
+
+  it('parseQuery validates query values and throws ZodError for invalid input', () => {
+    const schema = z.object({ page: z.coerce.number().int().positive() })
+    const req = { query: { page: '0' } } as unknown as Request
+
+    expect(() => parseQuery(schema, req)).toThrow('Number must be greater than 0')
+  })
+
+  it('parseParams returns validated path parameters', () => {
+    const schema = z.object({ vehicleId: z.string().min(1) })
+    const req = { params: { vehicleId: 'veh_123' } } as unknown as Request
+
+    expect(parseParams(schema, req)).toEqual({ vehicleId: 'veh_123' })
+  })
+})
@@ -0,0 +1,18 @@
+import type { Request } from 'express'
+import { ValidationError } from './errors'
+
+export function getRawBodyString(req: Request) {
+  if (!Buffer.isBuffer(req.body)) {
+    throw new ValidationError('Webhook route must be mounted with express.raw before JSON parsing')
+  }
+  return req.body.toString('utf8')
+}
+
+export function parseRawJsonBody<T = unknown>(req: Request): T {
+  const rawBody = getRawBodyString(req)
+  try {
+    return JSON.parse(rawBody) as T
+  } catch {
+    throw new ValidationError('Malformed webhook JSON')
+  }
+}
@@ -0,0 +1,271 @@
+import http from 'http'
+import { Server as SocketIOServer } from 'socket.io'
+import type { Socket } from 'socket.io'
+import cron from 'node-cron'
+import { redis } from './lib/redis'
+import { prisma } from './lib/prisma'
+import { assertStorageConfiguration } from './lib/storage'
+import { createApp, corsOrigins } from './app'
+import { verifyAnyActorToken } from './security/tokens'
+import { getSessionCookieName } from './security/sessionCookies'
+import { sendNotification } from './services/notificationService'
+import {
+  runTrialExpirationJob,
+  runPaymentPendingTimeoutJob,
+  runPastDueTimeoutJob,
+  runSuspensionTimeoutJob,
+  runPeriodEndCancellationJob,
+} from './modules/subscriptions/subscription.service'
+
+const app    = createApp()
+const server = http.createServer(app)
+assertStorageConfiguration()
+
+// ─── Socket.io ────────────────────────────────────────────────
+const io = new SocketIOServer(server, {
+  cors: { origin: corsOrigins, credentials: true, methods: ['GET', 'POST'] },
+})
+
+
+function readCookieFromHeader(cookieHeader: string | undefined, name: string): string | null {
+  if (!cookieHeader) return null
+
+  for (const chunk of cookieHeader.split(';')) {
+    const [rawName, ...rawValue] = chunk.trim().split('=')
+    if (rawName === name) return decodeURIComponent(rawValue.join('='))
+  }
+
+  return null
+}
+
+function getSocketSessionToken(socket: Socket): string | undefined {
+  const explicitToken = socket.handshake.auth?.token
+  if (typeof explicitToken === 'string' && explicitToken.trim()) return explicitToken.trim()
+
+  const cookieHeader = socket.request.headers.cookie
+  return (
+    readCookieFromHeader(cookieHeader, getSessionCookieName('employee')) ??
+    readCookieFromHeader(cookieHeader, getSessionCookieName('admin')) ??
+    readCookieFromHeader(cookieHeader, getSessionCookieName('renter')) ??
+    undefined
+  )
+}
+
+// Authenticate socket connections via JWT before joining user rooms
+io.use((socket, next) => {
+  const token = getSocketSessionToken(socket)
+  if (!token) return next() // unauthenticated connections allowed; they just don't join rooms
+  try {
+    const payload = verifyAnyActorToken(token)
+    ;(socket as any).authenticatedUserId = payload.sub
+    next()
+  } catch {
+    next(new Error('invalid_token'))
+  }
+})
+
+io.on('connection', (socket) => {
+  const userId = (socket as any).authenticatedUserId as string | undefined
+  if (userId) {
+    socket.join(`user:${userId}`)
+  }
+})
+
+// Redis pub/sub → broadcast to connected clients
+const subscriber = redis.duplicate()
+subscriber.psubscribe('notifications:*', (err) => {
+  if (err) console.error('[Redis] Subscribe error:', err)
+})
+subscriber.on('pmessage', (_pattern, channel, message) => {
+  try {
+    const parsed = JSON.parse(message)
+    const userId = channel.replace('notifications:', '')
+    io.to(`user:${userId}`).emit('notification', parsed)
+  } catch (err) {
+    console.error('[Redis] Invalid notification message:', err)
+  }
+})
+
+// ─── Scheduled jobs ───────────────────────────────────────────
+
+// Daily: flag expiring/expired licenses
+cron.schedule('0 8 * * *', async () => {
+  const customers = await prisma.customer.findMany({ where: { licenseExpiry: { not: null } } })
+  for (const c of customers) {
+    if (!c.licenseExpiry) continue
+    const daysLeft = Math.ceil((c.licenseExpiry.getTime() - Date.now()) / (1000 * 60 * 60 * 24))
+    const expired = c.licenseExpiry <= new Date()
+    const expiring = !expired && daysLeft < 90
+    if (expired !== c.licenseExpired || expiring !== c.licenseExpiringSoon) {
+      await prisma.customer.update({ where: { id: c.id }, data: { licenseExpired: expired, licenseExpiringSoon: expiring, licenseValidationStatus: expired ? 'EXPIRED' : expiring ? 'EXPIRING' : 'VALID' } })
+    }
+  }
+})
+
+// Hourly: expire trials that ended without payment
+cron.schedule('0 * * * *', async () => {
+  const n = await runTrialExpirationJob()
+  if (n > 0) console.log(`[subscription] trial_expiration: ${n} expired`)
+})
+
+// Hourly: payment_pending → past_due after 7 days
+cron.schedule('15 * * * *', async () => {
+  const n = await runPaymentPendingTimeoutJob()
+  if (n > 0) console.log(`[subscription] payment_pending_timeout: ${n} moved to past_due`)
+})
+
+// Hourly: past_due → suspended after 7 days
+cron.schedule('30 * * * *', async () => {
+  const n = await runPastDueTimeoutJob()
+  if (n > 0) console.log(`[subscription] past_due_timeout: ${n} suspended`)
+})
+
+// Daily: suspended → cancelled after 16 days; and period-end cancellations
+cron.schedule('0 1 * * *', async () => {
+  const nSuspend = await runSuspensionTimeoutJob()
+  const nPeriod  = await runPeriodEndCancellationJob()
+  if (nSuspend > 0) console.log(`[subscription] suspension_timeout: ${nSuspend} cancelled`)
+  if (nPeriod > 0)  console.log(`[subscription] period_end_cancel: ${nPeriod} cancelled`)
+})
+
+// Daily: send trial-ending reminders (3 days before trial end)
+cron.schedule('0 9 * * *', async () => {
+  const soon = new Date(Date.now() + 3 * 24 * 60 * 60 * 1000)
+  const subscriptions = await prisma.subscription.findMany({
+    where: { status: 'TRIALING', trialEndAt: { lte: soon, gte: new Date() } },
+    include: { company: { include: { employees: { where: { role: 'OWNER' } } } } },
+  })
+  for (const sub of subscriptions) {
+    const owner = sub.company.employees[0]
+    if (owner) {
+      await sendNotification({
+        type: 'SUBSCRIPTION_TRIAL_ENDING',
+        companyId: sub.companyId,
+        employeeId: owner.id,
+        channels: ['IN_APP'],
+        templateKey: 'subscription.trial_ending',
+        templateVariables: {
+          trialEndDate: sub.trialEndAt ?? new Date(Date.now() + 3 * 24 * 60 * 60 * 1000),
+        },
+      }).catch((err) => {
+        console.error('[Notifications] Failed to create trial ending reminder:', err?.message ?? String(err))
+      })
+    }
+  }
+})
+
+// Daily: notify companies about upcoming and overdue vehicle maintenance (date- and odometer-based).
+// Repeats every day until the owner logs a new service entry that pushes the due date/mileage into the future.
+cron.schedule('0 8 * * *', async () => {
+  const now = new Date()
+  const in30Days = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000)
+  const oneDayAgo = new Date(now.getTime() - 24 * 60 * 60 * 1000)
+
+  // Fetch all candidate logs (date-due or has an odometer target), ordered newest-first per vehicle+type.
+  // We keep only the LATEST log per vehicle+type so that once the owner logs a new service the
+  // old overdue log is superseded and notifications stop automatically.
+  const allCandidates = await prisma.maintenanceLog.findMany({
+    where: {
+      OR: [
+        { nextDueAt: { lte: in30Days } },
+        { nextDueMileage: { not: null } },
+      ],
+    },
+    include: { vehicle: { include: { company: { include: { employees: { where: { role: { in: ['OWNER', 'MANAGER'] }, isActive: true }, take: 1 } } } } } },
+    orderBy: { performedAt: 'desc' },
+  })
+
+  // Keep only the most-recent log per vehicle+type combination
+  const latestByKey = new Map<string, typeof allCandidates[number]>()
+  for (const log of allCandidates) {
+    const key = `${log.vehicleId}:${log.type}`
+    if (!latestByKey.has(key)) latestByKey.set(key, log)
+  }
+
+  for (const log of latestByKey.values()) {
+    const vehicle = log.vehicle
+    const company = vehicle.company
+    const recipient = company.employees[0]
+    if (!recipient) continue
+
+    // Determine date-based urgency
+    let isOverdueByDate = false
+    let daysLeft: number | null = null
+    let dueSoonByDate = false
+    if (log.nextDueAt) {
+      daysLeft = Math.ceil((log.nextDueAt.getTime() - now.getTime()) / (1000 * 60 * 60 * 24))
+      isOverdueByDate = log.nextDueAt <= now
+      dueSoonByDate = !isOverdueByDate && daysLeft <= 30
+    }
+
+    // Determine odometer-based urgency
+    let isOverdueByOdometer = false
+    let kmLeft: number | null = null
+    let dueSoonByOdometer = false
+    if (log.nextDueMileage != null && vehicle.mileage != null) {
+      kmLeft = log.nextDueMileage - vehicle.mileage
+      isOverdueByOdometer = kmLeft <= 0
+      dueSoonByOdometer = !isOverdueByOdometer && kmLeft <= 500
+    }
+
+    // Skip if the latest log is no longer due (owner has updated it)
+    const isOverdue = isOverdueByDate || isOverdueByOdometer
+    const isDueSoon = !isOverdue && (dueSoonByDate || dueSoonByOdometer)
+    if (!isOverdue && !isDueSoon) continue
+
+    // Dedup: don't send more than once per day for the same log
+    const alreadySent = await prisma.notification.findFirst({
+      where: {
+        type: 'VEHICLE_MAINTENANCE_DUE',
+        companyId: company.id,
+        createdAt: { gte: oneDayAgo },
+        data: { path: ['maintenanceLogId'], equals: log.id },
+      },
+    })
+    if (alreadySent) continue
+
+    // Build human-readable description
+    const dueParts: string[] = []
+    if (isOverdueByDate) dueParts.push(`overdue since ${log.nextDueAt!.toLocaleDateString()}`)
+    else if (dueSoonByDate && daysLeft != null) dueParts.push(`due in ${daysLeft} day${daysLeft === 1 ? '' : 's'}`)
+    if (isOverdueByOdometer) dueParts.push(`overdue by odometer (${Math.abs(kmLeft!).toLocaleString()} km ago)`)
+    else if (dueSoonByOdometer && kmLeft != null) dueParts.push(`${kmLeft.toLocaleString()} km remaining`)
+
+    const title = isOverdue
+      ? `Overdue: ${log.type} — ${vehicle.make} ${vehicle.model}`
+      : `${log.type} due soon — ${vehicle.make} ${vehicle.model}`
+    const body = `${log.type} for ${vehicle.make} ${vehicle.model} (${vehicle.licensePlate}): ${dueParts.join('; ')}. Please log the service to dismiss this reminder.`
+
+    await prisma.notification.create({
+      data: {
+        type: 'VEHICLE_MAINTENANCE_DUE',
+        title,
+        body,
+        data: {
+          vehicleId: vehicle.id,
+          maintenanceLogId: log.id,
+          maintenanceType: log.type,
+          isOverdue,
+          daysLeft,
+          kmLeft,
+          isOverdueByDate,
+          isOverdueByOdometer,
+        },
+        companyId: company.id,
+        employeeId: recipient.id,
+        channel: 'IN_APP',
+        status: 'DELIVERED',
+      },
+    })
+  }
+})
+
+// ─── Start ────────────────────────────────────────────────────
+const PORT = Number(process.env.API_PORT ?? 4000)
+const HOST = process.env.API_HOST ?? '0.0.0.0'
+
+server.listen(PORT, HOST, () => {
+  console.log(`[API] Server running on ${HOST}:${PORT}`)
+})
+
+export { app, io }
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+  formatDate,
+  marketplaceReservationEmail,
+  resetPasswordEmail,
+  signupEmail,
+} from './emailTranslations'
+
+describe('emailTranslations', () => {
+  const trialEnd = new Date('2026-07-15T12:00:00.000Z')
+
+  it('renders signup subjects in every supported locale', () => {
+    expect(signupEmail.subject('en')).toContain('workspace')
+    expect(signupEmail.subject('fr')).toContain('espace')
+    expect(signupEmail.subject('ar')).toContain('جاهزة')
+  })
+
+  it('renders localized signup text with billing and provider details', () => {
+    const text = signupEmail.text({
+      firstName: 'Aya',
+      companyName: 'Atlas Cars',
+      plan: 'PRO',
+      billingPeriod: 'ANNUAL',
+      currency: 'MAD',
+      paymentProvider: 'AmanPay',
+      trialEnd,
+    }, 'fr')
+
+    expect(text).toContain('Bonjour Aya')
+    expect(text).toContain('Atlas Cars')
+    expect(text).toContain('Forfait : PRO (annuel)')
+    expect(text).toContain('Fournisseur de paiement principal : AmanPay')
+  })
+
+  it('marks Arabic reset-password HTML as right-to-left and embeds the reset URL', () => {
+    const html = resetPasswordEmail.html('https://example.test/reset/token', 'Mina', 45, 'ar')
+
+    expect(html).toContain('dir="rtl"')
+    expect(html).toContain('https://example.test/reset/token')
+    expect(html).toContain('45')
+  })
+
+  it('includes optional contact phone in marketplace reservation HTML when present', () => {
+    const html = marketplaceReservationEmail.html({
+      firstName: 'Yassine',
+      vehicleYear: 2024,
+      vehicleMake: 'Dacia',
+      vehicleModel: 'Duster',
+      companyName: 'Atlas Cars',
+      startDate: new Date('2026-08-01T00:00:00.000Z'),
+      endDate: new Date('2026-08-05T00:00:00.000Z'),
+      totalDays: 4,
+      rateDisplay: '400.00',
+      totalDisplay: '1600.00',
+      email: 'yassine@example.test',
+      phone: '+212600000000',
+    }, 'en')
+
+    expect(html).toContain('2024 Dacia Duster')
+    expect(html).toContain('Atlas Cars')
+    expect(html).toContain('yassine@example.test or +212600000000')
+  })
+
+  it('formats dates with the locale-specific formatter', () => {
+    expect(formatDate(new Date('2026-02-03T00:00:00.000Z'), 'en')).toContain('2026')
+    expect(formatDate(new Date('2026-02-03T00:00:00.000Z'), 'fr')).toContain('2026')
+    expect(formatDate(new Date('2026-02-03T00:00:00.000Z'), 'ar')).toMatch(/2026|٢٠٢٦/)
+    expect(formatDate(new Date('2026-02-03T00:00:00.000Z'), 'ar')).toContain('فبراير')
+  })
+})
@@ -0,0 +1,290 @@
+export type Lang = 'en' | 'fr' | 'ar'
+
+function t<T>(map: Record<Lang, T>, lang: Lang): T {
+  return map[lang] ?? map['fr']
+}
+
+const dateLocale: Record<Lang, string> = { en: 'en-GB', fr: 'fr-FR', ar: 'ar-MA' }
+
+export function formatDate(date: Date, lang: Lang, opts?: Intl.DateTimeFormatOptions): string {
+  return date.toLocaleDateString(dateLocale[lang], opts ?? { year: 'numeric', month: 'long', day: 'numeric' })
+}
+
+// ─── Signup confirmation ──────────────────────────────────────────────────────
+
+export const signupEmail = {
+  subject: (lang: Lang) => t({
+    en: 'Your workspace is ready — RentalDriveGo',
+    fr: 'Votre espace de travail est prêt — RentalDriveGo',
+    ar: 'مساحة عملك جاهزة — RentalDriveGo',
+  }, lang),
+
+  text: (opts: {
+    firstName: string
+    companyName: string
+    plan: string
+    billingPeriod: string
+    currency: string
+    paymentProvider: string
+    trialEnd: Date
+  }, lang: Lang): string => {
+    const trialStr = formatDate(opts.trialEnd, lang)
+    return t({
+      en: [
+        `Hi ${opts.firstName},`,
+        '',
+        `Your RentalDriveGo workspace for ${opts.companyName} has been created successfully.`,
+        `Plan: ${opts.plan} (${opts.billingPeriod.toLowerCase()})`,
+        `Currency: ${opts.currency}`,
+        `Primary payment provider: ${opts.paymentProvider}`,
+        `Free trial ends on ${trialStr}.`,
+        '',
+        'Your workspace is ready. Sign in with the email and password you chose during signup.',
+        '',
+        'RentalDriveGo',
+      ].join('\n'),
+      fr: [
+        `Bonjour ${opts.firstName},`,
+        '',
+        `Votre espace de travail RentalDriveGo pour ${opts.companyName} a été créé avec succès.`,
+        `Forfait : ${opts.plan} (${opts.billingPeriod === 'MONTHLY' ? 'mensuel' : 'annuel'})`,
+        `Devise : ${opts.currency}`,
+        `Fournisseur de paiement principal : ${opts.paymentProvider}`,
+        `La période d'essai gratuit se termine le ${trialStr}.`,
+        '',
+        "Votre espace de travail est prêt. Connectez-vous avec l'e-mail et le mot de passe choisis lors de l'inscription.",
+        '',
+        'RentalDriveGo',
+      ].join('\n'),
+      ar: [
+        `مرحباً ${opts.firstName}،`,
+        '',
+        `تم إنشاء مساحة عمل RentalDriveGo الخاصة بـ ${opts.companyName} بنجاح.`,
+        `الخطة: ${opts.plan} (${opts.billingPeriod === 'MONTHLY' ? 'شهري' : 'سنوي'})`,
+        `العملة: ${opts.currency}`,
+        `مزود الدفع الرئيسي: ${opts.paymentProvider}`,
+        `تنتهي الفترة التجريبية المجانية في ${trialStr}.`,
+        '',
+        'مساحة عملك جاهزة. سجّل الدخول باستخدام البريد الإلكتروني وكلمة المرور التي اخترتهما عند التسجيل.',
+        '',
+        'RentalDriveGo',
+      ].join('\n'),
+    }, lang)
+  },
+}
+
+// ─── Password reset ───────────────────────────────────────────────────────────
+
+export const resetPasswordEmail = {
+  subject: (lang: Lang) => t({
+    en: 'Reset your RentalDriveGo password',
+    fr: 'Réinitialisez votre mot de passe RentalDriveGo',
+    ar: 'إعادة تعيين كلمة مرور RentalDriveGo',
+  }, lang),
+
+  html: (resetUrl: string, firstName: string, expireMinutes: number, lang: Lang): string => {
+    const isRtl = lang === 'ar'
+    const dir = isRtl ? 'rtl' : 'ltr'
+    return t({
+      en: `<div dir="ltr" style="font-family:sans-serif;max-width:560px;margin:auto;padding:32px;color:#1c1917">
+        <p>Hi ${firstName},</p>
+        <p>You requested a password reset for your RentalDriveGo workspace account.</p>
+        <p><a href="${resetUrl}" style="background:#1d4ed8;color:#fff;padding:12px 24px;border-radius:8px;text-decoration:none;display:inline-block;font-weight:600;">Reset your password</a></p>
+        <p>This link expires in ${expireMinutes} minutes. If you did not request this, you can safely ignore this email.</p>
+        <p>RentalDriveGo</p>
+      </div>`,
+      fr: `<div dir="ltr" style="font-family:sans-serif;max-width:560px;margin:auto;padding:32px;color:#1c1917">
+        <p>Bonjour ${firstName},</p>
+        <p>Vous avez demandé la réinitialisation du mot de passe de votre compte RentalDriveGo.</p>
+        <p><a href="${resetUrl}" style="background:#1d4ed8;color:#fff;padding:12px 24px;border-radius:8px;text-decoration:none;display:inline-block;font-weight:600;">Réinitialiser mon mot de passe</a></p>
+        <p>Ce lien expire dans ${expireMinutes} minutes. Si vous n'avez pas fait cette demande, ignorez simplement cet e-mail.</p>
+        <p>RentalDriveGo</p>
+      </div>`,
+      ar: `<div dir="rtl" style="font-family:sans-serif;max-width:560px;margin:auto;padding:32px;color:#1c1917">
+        <p>مرحباً ${firstName}،</p>
+        <p>طلبت إعادة تعيين كلمة مرور حساب RentalDriveGo الخاص بك.</p>
+        <p><a href="${resetUrl}" style="background:#1d4ed8;color:#fff;padding:12px 24px;border-radius:8px;text-decoration:none;display:inline-block;font-weight:600;">إعادة تعيين كلمة المرور</a></p>
+        <p>تنتهي صلاحية هذا الرابط خلال ${expireMinutes} دقيقة. إذا لم تطلب ذلك، يمكنك تجاهل هذا البريد الإلكتروني بأمان.</p>
+        <p>RentalDriveGo</p>
+      </div>`,
+    }, lang)
+  },
+
+  text: (resetUrl: string, firstName: string, expireMinutes: number, lang: Lang): string => t({
+    en: `Hi ${firstName},\n\nReset your password here: ${resetUrl}\n\nThis link expires in ${expireMinutes} minutes.\n\nRentalDriveGo`,
+    fr: `Bonjour ${firstName},\n\nRéinitialisez votre mot de passe ici : ${resetUrl}\n\nCe lien expire dans ${expireMinutes} minutes.\n\nRentalDriveGo`,
+    ar: `مرحباً ${firstName}،\n\nأعد تعيين كلمة مرورك هنا: ${resetUrl}\n\nينتهي هذا الرابط خلال ${expireMinutes} دقيقة.\n\nRentalDriveGo`,
+  }, lang),
+}
+
+// ─── Marketplace reservation request ─────────────────────────────────────────
+
+export const marketplaceReservationEmail = {
+  subject: (vehicleName: string, lang: Lang) => t({
+    en: `Reservation Request Received — ${vehicleName}`,
+    fr: `Demande de réservation reçue — ${vehicleName}`,
+    ar: `تم استلام طلب الحجز — ${vehicleName}`,
+  }, lang),
+
+  html: (opts: {
+    firstName: string
+    vehicleYear: number
+    vehicleMake: string
+    vehicleModel: string
+    companyName: string
+    startDate: Date
+    endDate: Date
+    totalDays: number
+    rateDisplay: string
+    totalDisplay: string
+    email: string
+    phone?: string
+  }, lang: Lang): string => {
+    const startStr = formatDate(opts.startDate, lang)
+    const endStr = formatDate(opts.endDate, lang)
+    const isRtl = lang === 'ar'
+    const l = t({
+      en: {
+        greeting: `Hi ${opts.firstName},`,
+        intro: 'Your reservation request has been received and is pending company confirmation.',
+        company: 'Company', pickup: 'Pick-up date', returnD: 'Return date',
+        duration: 'Duration', daily: 'Daily rate', total: 'Estimated total', days: 'day(s)',
+        footer: `The company will review your request and get in touch shortly. You may be contacted at ${opts.email}${opts.phone ? ` or ${opts.phone}` : ''}.`,
+      },
+      fr: {
+        greeting: `Bonjour ${opts.firstName},`,
+        intro: 'Votre demande de réservation a été reçue et est en attente de confirmation.',
+        company: 'Société', pickup: 'Date de prise en charge', returnD: 'Date de retour',
+        duration: 'Durée', daily: 'Tarif journalier', total: 'Total estimé', days: 'jour(s)',
+        footer: `La société examinera votre demande et vous contactera prochainement. Vous pouvez être contacté à ${opts.email}${opts.phone ? ` ou ${opts.phone}` : ''}.`,
+      },
+      ar: {
+        greeting: `مرحباً ${opts.firstName}،`,
+        intro: 'تم استلام طلب الحجز وهو في انتظار تأكيد الشركة.',
+        company: 'الشركة', pickup: 'تاريخ الاستلام', returnD: 'تاريخ الإرجاع',
+        duration: 'المدة', daily: 'السعر اليومي', total: 'الإجمالي التقديري', days: 'يوم',
+        footer: `ستراجع الشركة طلبك وستتواصل معك قريباً. يمكن التواصل معك على ${opts.email}${opts.phone ? ` أو ${opts.phone}` : ''}.`,
+      },
+    }, lang)
+
+    return `
+      <div style="font-family:sans-serif;max-width:560px;margin:auto;padding:32px;color:#1c1917;direction:${isRtl ? 'rtl' : 'ltr'}">
+        <h2 style="margin-bottom:4px">${l.greeting}</h2>
+        <p style="color:#57534e">${l.intro}</p>
+        <hr style="border:none;border-top:1px solid #e7e5e4;margin:24px 0"/>
+        <h3 style="margin-bottom:12px">${opts.vehicleYear} ${opts.vehicleMake} ${opts.vehicleModel}</h3>
+        <p><strong>${l.company}:</strong> ${opts.companyName}</p>
+        <p><strong>${l.pickup}:</strong> ${startStr}</p>
+        <p><strong>${l.returnD}:</strong> ${endStr}</p>
+        <p><strong>${l.duration}:</strong> ${opts.totalDays} ${l.days}</p>
+        <p><strong>${l.daily}:</strong> ${opts.rateDisplay} MAD</p>
+        <p><strong>${l.total}:</strong> ${opts.totalDisplay} MAD</p>
+        <hr style="border:none;border-top:1px solid #e7e5e4;margin:24px 0"/>
+        <p style="color:#57534e;font-size:13px">${l.footer}</p>
+      </div>
+    `
+  },
+
+  text: (opts: {
+    firstName: string
+    vehicleYear: number
+    vehicleMake: string
+    vehicleModel: string
+    companyName: string
+    startDate: Date
+    endDate: Date
+    totalDays: number
+    rateDisplay: string
+    totalDisplay: string
+  }, lang: Lang): string => {
+    const startStr = formatDate(opts.startDate, lang)
+    const endStr = formatDate(opts.endDate, lang)
+    return t({
+      en: `Hi ${opts.firstName},\n\nYour reservation request for the ${opts.vehicleYear} ${opts.vehicleMake} ${opts.vehicleModel} from ${opts.companyName} has been received.\n\nDates: ${startStr} → ${endStr}\nDuration: ${opts.totalDays} day(s)\nDaily rate: ${opts.rateDisplay} MAD\nEstimated total: ${opts.totalDisplay} MAD\n\nThe company will confirm your request shortly.\n\nThank you!`,
+      fr: `Bonjour ${opts.firstName},\n\nVotre demande de réservation pour la ${opts.vehicleYear} ${opts.vehicleMake} ${opts.vehicleModel} auprès de ${opts.companyName} a été reçue.\n\nDates : ${startStr} → ${endStr}\nDurée : ${opts.totalDays} jour(s)\nTarif journalier : ${opts.rateDisplay} MAD\nTotal estimé : ${opts.totalDisplay} MAD\n\nLa société confirmera votre demande prochainement.\n\nMerci !`,
+      ar: `مرحباً ${opts.firstName}،\n\nتم استلام طلب حجزك لسيارة ${opts.vehicleYear} ${opts.vehicleMake} ${opts.vehicleModel} من ${opts.companyName}.\n\nالتواريخ: ${startStr} → ${endStr}\nالمدة: ${opts.totalDays} يوم\nالسعر اليومي: ${opts.rateDisplay} MAD\nالإجمالي التقديري: ${opts.totalDisplay} MAD\n\nستؤكد الشركة طلبك قريباً.\n\nشكراً!`,
+    }, lang)
+  },
+}
+
+// ─── Booking confirmed ────────────────────────────────────────────────────────
+
+export const bookingConfirmedNotif = {
+  title: (lang: Lang) => t({
+    en: 'Booking Confirmed',
+    fr: 'Réservation confirmée',
+    ar: 'تم تأكيد الحجز',
+  }, lang),
+  body: (lang: Lang) => t({
+    en: 'Your booking has been confirmed.',
+    fr: 'Votre réservation a été confirmée.',
+    ar: 'تم تأكيد حجزك.',
+  }, lang),
+}
+
+// ─── Post-rental review request ───────────────────────────────────────────────
+
+export const reviewRequestEmail = {
+  subject: (vehicleLabel: string, lang: Lang) => t({
+    en: `How was your rental? — ${vehicleLabel}`,
+    fr: `Comment s'est passée votre location ? — ${vehicleLabel}`,
+    ar: `كيف كانت تجربة الإيجار؟ — ${vehicleLabel}`,
+  }, lang),
+
+  html: (opts: {
+    firstName: string
+    companyName: string
+    vehicleLabel: string
+    reviewUrl: string
+  }, lang: Lang): string => {
+    const isRtl = lang === 'ar'
+    const l = t({
+      en: {
+        greeting: `Hi ${opts.firstName},`,
+        body1: `Thank you for renting with <strong>${opts.companyName}</strong>. We hope you enjoyed your <strong>${opts.vehicleLabel}</strong>.`,
+        body2: 'Your feedback helps the company improve and helps other customers make informed choices. It only takes 30 seconds.',
+        cta: 'Leave a review',
+        disclaimer: 'This link is unique to your reservation and can only be used once. If you did not rent a vehicle recently, you can ignore this email.',
+      },
+      fr: {
+        greeting: `Bonjour ${opts.firstName},`,
+        body1: `Merci d'avoir loué chez <strong>${opts.companyName}</strong>. Nous espérons que vous avez apprécié votre <strong>${opts.vehicleLabel}</strong>.`,
+        body2: "Votre avis aide la société à s'améliorer et aide les autres clients à faire des choix éclairés. Cela ne prend que 30 secondes.",
+        cta: 'Laisser un avis',
+        disclaimer: "Ce lien est unique à votre réservation et ne peut être utilisé qu'une seule fois. Si vous n'avez pas loué de véhicule récemment, vous pouvez ignorer cet e-mail.",
+      },
+      ar: {
+        greeting: `مرحباً ${opts.firstName}،`,
+        body1: `شكراً لاختيار <strong>${opts.companyName}</strong>. نأمل أنك استمتعت بـ <strong>${opts.vehicleLabel}</strong>.`,
+        body2: 'تساعد ملاحظاتك الشركة على التحسين وتساعد العملاء الآخرين على اتخاذ قرارات مستنيرة. لا يستغرق الأمر سوى 30 ثانية.',
+        cta: 'اترك تقييماً',
+        disclaimer: 'هذا الرابط فريد لحجزك ولا يمكن استخدامه إلا مرة واحدة. إذا لم تستأجر مركبة مؤخراً، يمكنك تجاهل هذا البريد الإلكتروني.',
+      },
+    }, lang)
+
+    return `
+      <div style="font-family:sans-serif;max-width:560px;margin:auto;padding:32px;color:#1c1917;direction:${isRtl ? 'rtl' : 'ltr'}">
+        <h2 style="margin-bottom:4px">${l.greeting}</h2>
+        <p style="color:#57534e">${l.body1}</p>
+        <p style="color:#57534e">${l.body2}</p>
+        <div style="margin:32px 0;text-align:center">
+          <a href="${opts.reviewUrl}" style="background:#1c1917;color:#ffffff;padding:14px 32px;border-radius:999px;text-decoration:none;font-weight:600;font-size:15px;display:inline-block">
+            ${l.cta}
+          </a>
+        </div>
+        <p style="color:#a8a29e;font-size:12px">${l.disclaimer}</p>
+      </div>
+    `
+  },
+
+  text: (opts: {
+    firstName: string
+    companyName: string
+    vehicleLabel: string
+    reviewUrl: string
+  }, lang: Lang): string => t({
+    en: `Hi ${opts.firstName},\n\nThank you for renting with ${opts.companyName}. We hope you enjoyed your ${opts.vehicleLabel}.\n\nLeave a review here (one-time link):\n${opts.reviewUrl}\n\nThank you!`,
+    fr: `Bonjour ${opts.firstName},\n\nMerci d'avoir loué chez ${opts.companyName}. Nous espérons que vous avez apprécié votre ${opts.vehicleLabel}.\n\nLaissez un avis ici (lien unique) :\n${opts.reviewUrl}\n\nMerci !`,
+    ar: `مرحباً ${opts.firstName}،\n\nشكراً لاختيار ${opts.companyName}. نأمل أنك استمتعت بـ ${opts.vehicleLabel}.\n\nاترك تقييماً هنا (رابط فريد):\n${opts.reviewUrl}\n\nشكراً!`,
+  }, lang),
+}
@@ -0,0 +1,172 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeAndFormat, toTitleCase, toTitleCaseAll, toLowerCase, toUpperCase, preserveOriginal, getMaxLength } from './inputValidation'
+
+describe('toTitleCase', () => {
+  it('uppercases first letter and lowercases rest of each word', () => {
+    expect(toTitleCase('john doe')).toBe('John Doe')
+    expect(toTitleCase('MARIA')).toBe('Maria')
+    expect(toTitleCase('new york')).toBe('New York')
+  })
+
+  it('preserves numbers and special chars that survive sanitization', () => {
+    expect(toTitleCase('123 main st.')).toBe('123 Main St.')
+  })
+
+  it('handles single word', () => {
+    expect(toTitleCase('hello')).toBe('Hello')
+  })
+})
+
+describe('toTitleCaseAll', () => {
+  it('uppercases first letter of every word', () => {
+    expect(toTitleCaseAll('acme corporation ltd.')).toBe('Acme Corporation Ltd.')
+    expect(toTitleCaseAll('123 main street, apt 4b')).toBe('123 Main Street, Apt 4b')
+  })
+})
+
+describe('toLowerCase', () => {
+  it('lowercases all characters', () => {
+    expect(toLowerCase('John.Doe@Example.COM')).toBe('john.doe@example.com')
+    expect(toLowerCase('ALLCAPS')).toBe('allcaps')
+  })
+})
+
+describe('toUpperCase', () => {
+  it('uppercases letters, leaves numbers unchanged', () => {
+    expect(toUpperCase('abc-123')).toBe('ABC-123')
+    expect(toUpperCase('ab123cd')).toBe('AB123CD')
+  })
+})
+
+describe('preserveOriginal', () => {
+  it('returns the string unchanged', () => {
+    expect(preserveOriginal('SW1A 1AA')).toBe('SW1A 1AA')
+    expect(preserveOriginal('12345')).toBe('12345')
+  })
+})
+
+describe('sanitizeAndFormat', () => {
+  // ─── Title Case fields
+
+  it('formats name fields (title case, max 50)', () => {
+    expect(sanitizeAndFormat('john doe', 'name')).toBe('John Doe')
+    expect(sanitizeAndFormat('MARIA', 'name')).toBe('Maria')
+  })
+
+  it('formats streetAddress (title case, max 100)', () => {
+    expect(sanitizeAndFormat('123 main st.', 'streetAddress')).toBe('123 Main St')
+    expect(sanitizeAndFormat('elm street 42', 'streetAddress')).toBe('Elm Street 42')
+  })
+
+  it('formats city (title case, max 50)', () => {
+    expect(sanitizeAndFormat('new york', 'city')).toBe('New York')
+  })
+
+  it('formats pickupLocation and returnLocation', () => {
+    expect(sanitizeAndFormat('airport terminal 1', 'pickupLocation')).toBe('Airport Terminal 1')
+    expect(sanitizeAndFormat('downtown garage', 'returnLocation')).toBe('Downtown Garage')
+  })
+
+  it('formats country (title case)', () => {
+    expect(sanitizeAndFormat('united kingdom', 'country')).toBe('United Kingdom')
+  })
+
+  // ─── Title Case All fields
+
+  it('formats fullAddress (title case all, max 200)', () => {
+    expect(sanitizeAndFormat('123 main street, apt 4b', 'fullAddress')).toBe('123 Main Street, Apt 4b')
+  })
+
+  it('formats commercialName (title case all, max 100)', () => {
+    expect(sanitizeAndFormat('acme corporation', 'commercialName')).toBe('Acme Corporation')
+  })
+
+  it('formats legalCompanyName (title case all, max 100)', () => {
+    expect(sanitizeAndFormat('global rentals llc', 'legalCompanyName')).toBe('Global Rentals Llc')
+  })
+
+  // ─── Email
+
+  it('formats email (lowercase)', () => {
+    expect(sanitizeAndFormat('John.Doe@Example.COM', 'email')).toBe('john.doe@example.com')
+  })
+
+  // ─── Uppercase fields
+
+  it('formats licensePlate (uppercase, preserves hyphens)', () => {
+    expect(sanitizeAndFormat('abc-123', 'licensePlate')).toBe('ABC-123')
+  })
+
+  it('formats VIN (uppercase)', () => {
+    expect(sanitizeAndFormat('1hgbh41jxmn109186', 'vin')).toBe('1HGBH41JXMN109186')
+  })
+
+  it('formats passportNumber (uppercase)', () => {
+    expect(sanitizeAndFormat('ab123456', 'passportNumber')).toBe('AB123456')
+  })
+
+  it('formats driverLicenseNumber (uppercase, preserves hyphens)', () => {
+    expect(sanitizeAndFormat('d123-456-789', 'driverLicenseNumber')).toBe('D123-456-789')
+  })
+
+  it('formats licenseCategory (uppercase)', () => {
+    expect(sanitizeAndFormat('b', 'licenseCategory')).toBe('B')
+  })
+
+  // ─── Car fields
+
+  it('formats carMark (title case)', () => {
+    expect(sanitizeAndFormat('TOYOTA', 'carMark')).toBe('Toyota')
+    expect(sanitizeAndFormat('mercedes-benz', 'carMark')).toBe('Mercedes-Benz')
+  })
+
+  it('formats carModel (title case)', () => {
+    expect(sanitizeAndFormat('corolla', 'carModel')).toBe('Corolla')
+  })
+
+  it('formats carColor (title case)', () => {
+    expect(sanitizeAndFormat('midnight-blue', 'carColor')).toBe('Midnight-Blue')
+  })
+
+  // ─── ZIP Code (preserved)
+
+  it('preserves ZIP code format', () => {
+    expect(sanitizeAndFormat('12345', 'zipCode')).toBe('12345')
+    expect(sanitizeAndFormat('SW1A 1AA', 'zipCode')).toBe('SW1A 1AA')
+  })
+
+  // ─── Sanitization
+
+  it('removes disallowed characters', () => {
+    expect(sanitizeAndFormat('John!@#', 'name')).toBe('John')
+  })
+
+  it('strips disallowed characters including angle brackets', () => {
+    const result = sanitizeAndFormat('test<script>alert(1)</script>', 'name')
+    expect(result).toBe('Testscriptalertscript')
+  })
+
+  // ─── Truncation
+
+  it('truncates to max length', () => {
+    const longName = 'A'.repeat(60)
+    expect(sanitizeAndFormat(longName, 'name')).toHaveLength(50)
+  })
+
+  it('does not truncate strings within limit', () => {
+    expect(sanitizeAndFormat('John', 'name')).toHaveLength(4)
+  })
+})
+
+describe('getMaxLength', () => {
+  it('returns correct max lengths', () => {
+    expect(getMaxLength('name')).toBe(50)
+    expect(getMaxLength('streetAddress')).toBe(100)
+    expect(getMaxLength('fullAddress')).toBe(200)
+    expect(getMaxLength('email')).toBe(100)
+    expect(getMaxLength('licensePlate')).toBe(30)
+    expect(getMaxLength('zipCode')).toBe(10)
+    expect(getMaxLength('carMark')).toBe(30)
+  })
+})
+
@@ -0,0 +1,136 @@
+/**
+ * User Input Validation and Formatting Library
+ *
+ * Implements the rules defined in docs/input_validation_plan.md.
+ * Provides formatting functions and a Zod-integrated pipeline that:
+ *   1. Removes disallowed characters
+ *   2. Trims leading/trailing whitespace
+ *   3. Validates format (email)
+ *   4. Applies case transformation
+ *   5. Truncates to max length
+ */
+
+// ─── Character class definitions ───────────────────────────────
+
+const LETTERS_NUMBERS = 'a-zA-Z0-9'
+const LETTERS_NUMBERS_HYPHEN = `${LETTERS_NUMBERS}\\-`
+const LETTERS_SPACES_HYPHEN = 'a-zA-Z\\s\\-'
+const BASE_TEXT = `${LETTERS_NUMBERS}\\s\\-\\/`
+const EXTENDED_TEXT = `${BASE_TEXT},`
+
+// ─── Field type definitions ────────────────────────────────────
+
+export type FieldType =
+  | 'name' | 'nationality' | 'streetAddress' | 'city'
+  | 'pickupLocation' | 'returnLocation' | 'country'
+  | 'fullAddress' | 'commercialName' | 'legalCompanyName'
+  | 'email'
+  | 'licensePlate' | 'vin' | 'cin' | 'passportNumber'
+  | 'internationalPermitNumber' | 'driverLicenseNumber'
+  | 'licenseCategory' | 'iceNumber' | 'commercialRegistry'
+  | 'carMark' | 'carModel' | 'carColor'
+  | 'zipCode'
+
+interface FieldConfig {
+  maxLength: number
+  allowedPattern: RegExp
+  transform: (value: string) => string
+}
+
+// ─── Formatting functions ──────────────────────────────────────
+
+/** Uppercase first letter of each word, lowercase the rest */
+export function toTitleCase(str: string): string {
+  return str.replace(/\b\w+/g, (word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+}
+
+/** Uppercase first letter of every word */
+export function toTitleCaseAll(str: string): string {
+  return str.replace(/\b\w+/g, (word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+}
+
+export function toLowerCase(str: string): string {
+  return str.toLowerCase()
+}
+
+/** Uppercase letters only, leave numbers unchanged */
+export function toUpperCase(str: string): string {
+  return str.replace(/[a-zA-Z]/g, (char) => char.toUpperCase())
+}
+
+export function preserveOriginal(str: string): string {
+  return str
+}
+
+// ─── Field configuration ───────────────────────────────────────
+
+const FIELD_CONFIGS: Record<FieldType, FieldConfig> = {
+  // Group 1: Title Case
+  name:           { maxLength: 50,  allowedPattern: new RegExp('^[' + LETTERS_SPACES_HYPHEN + ']*$'),    transform: toTitleCase },
+  nationality:    { maxLength: 50,  allowedPattern: new RegExp('^[' + LETTERS_SPACES_HYPHEN + ']*$'),    transform: toTitleCase },
+  streetAddress:  { maxLength: 100, allowedPattern: new RegExp('^[' + BASE_TEXT + ']*$'),                transform: toTitleCase },
+  city:           { maxLength: 50,  allowedPattern: new RegExp('^[' + LETTERS_SPACES_HYPHEN + ']*$'),    transform: toTitleCase },
+  pickupLocation: { maxLength: 50,  allowedPattern: new RegExp('^[' + BASE_TEXT + ']*$'),                transform: toTitleCase },
+  returnLocation: { maxLength: 50,  allowedPattern: new RegExp('^[' + BASE_TEXT + ']*$'),                transform: toTitleCase },
+  country:        { maxLength: 50,  allowedPattern: new RegExp('^[' + LETTERS_SPACES_HYPHEN + ']*$'),    transform: toTitleCase },
+
+  // Group 2: Title Case All
+  fullAddress:      { maxLength: 200, allowedPattern: new RegExp('^[' + EXTENDED_TEXT + ']*$'),           transform: toTitleCaseAll },
+  commercialName:   { maxLength: 100, allowedPattern: new RegExp('^[' + EXTENDED_TEXT + ']*$'),           transform: toTitleCaseAll },
+  legalCompanyName: { maxLength: 100, allowedPattern: new RegExp('^[' + EXTENDED_TEXT + ']*$'),           transform: toTitleCaseAll },
+
+  // Group 3: Lowercase — email
+  email: { maxLength: 100, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS + '@._%\\+\\-]*$'), transform: toLowerCase },
+
+  // Group 4: Uppercase (hyphens allowed per plan examples: "abc-123" → "ABC-123")
+  licensePlate:             { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  vin:                      { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  cin:                      { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  passportNumber:           { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  internationalPermitNumber:{ maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  driverLicenseNumber:      { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  licenseCategory:          { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  iceNumber:                { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+  commercialRegistry:       { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS_HYPHEN + ']*$'), transform: toUpperCase },
+
+  // Group 5: Car fields
+  carMark:  { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS + '\\s\\-]*$'), transform: toTitleCase },
+  carModel: { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS + '\\s\\-]*$'), transform: toTitleCase },
+  carColor: { maxLength: 30, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS + '\\s\\-]*$'), transform: toTitleCase },
+
+  // Group 6: Preserved (spaces for UK postcodes like "SW1A 1AA")
+  zipCode: { maxLength: 10, allowedPattern: new RegExp('^[' + LETTERS_NUMBERS + '\\s\\-]*$'), transform: preserveOriginal },
+}
+
+// ─── Public API ────────────────────────────────────────────────
+
+/** Full processing pipeline: sanitize → trim → format → truncate */
+export function sanitizeAndFormat(value: string, fieldType: FieldType): string {
+  const config = FIELD_CONFIGS[fieldType]
+
+  // Step 1: Remove disallowed characters
+  let sanitized = ''
+  for (const char of value) {
+    if (config.allowedPattern.test(char)) {
+      sanitized += char
+    }
+  }
+
+  // Step 2: Trim
+  sanitized = sanitized.trim()
+
+  // Step 3: Apply case transformation
+  const formatted = config.transform(sanitized)
+
+  // Step 4: Truncate
+  if (formatted.length > config.maxLength) {
+    return formatted.slice(0, config.maxLength)
+  }
+
+  return formatted
+}
+
+/** Get the max length for a given field type */
+export function getMaxLength(fieldType: FieldType): number {
+  return FIELD_CONFIGS[fieldType].maxLength
+}
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { isDatabaseUnavailableError } from './isDatabaseUnavailable'
+
+describe('isDatabaseUnavailableError', () => {
+  it('detects Prisma P1001 connection failures', () => {
+    expect(isDatabaseUnavailableError({ code: 'P1001' })).toBe(true)
+  })
+
+  it('detects database reachability failures by message', () => {
+    expect(isDatabaseUnavailableError({ message: "Can't reach database server at postgres:5432" })).toBe(true)
+  })
+
+  it('rejects unrelated, null, and primitive errors', () => {
+    expect(isDatabaseUnavailableError({ code: 'P2002' })).toBe(false)
+    expect(isDatabaseUnavailableError(new Error('network hiccup'))).toBe(false)
+    expect(isDatabaseUnavailableError(null)).toBe(false)
+    expect(isDatabaseUnavailableError('P1001')).toBe(false)
+  })
+})
@@ -0,0 +1,5 @@
+export function isDatabaseUnavailableError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false
+  const candidate = error as { code?: string; message?: string }
+  return candidate.code === 'P1001' || candidate.message?.includes("Can't reach database server") === true
+}
@@ -0,0 +1,13 @@
+import { PrismaClient } from '@rentaldrivego/database/client'
+
+const globalForPrisma = global as unknown as { prisma: PrismaClient }
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+  })
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
@@ -0,0 +1,10 @@
+import Redis from 'ioredis'
+
+export const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379', {
+  maxRetriesPerRequest: 3,
+  retryStrategy: (times) => Math.min(times * 50, 2000),
+})
+
+redis.on('error', (err) => {
+  console.error('[Redis] Connection error:', err.message)
+})
@@ -0,0 +1,62 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  assertStorageConfiguration,
+  deleteImage,
+  getPrivateStorageRoot,
+  getProtectedCustomerLicenseImageUrl,
+  getPublicStorageRoot,
+  getStorageRoot,
+  resolveStoredFilePath,
+  uploadImage,
+} from './storage'
+
+const originalEnv = { ...process.env }
+
+describe('storage', () => {
+  afterEach(() => {
+    process.env = { ...originalEnv }
+  })
+
+  it('uses FILE_STORAGE_ROOT when configured and builds protected customer license URLs from dashboard URL', () => {
+    process.env.FILE_STORAGE_ROOT = '/tmp/rdg-storage'
+    process.env.DASHBOARD_URL = 'https://dashboard.rentaldrivego.test/dashboard/'
+
+    expect(getStorageRoot()).toBe('/tmp/rdg-storage')
+    expect(getPublicStorageRoot()).toBe('/tmp/rdg-storage/public')
+    expect(getPrivateStorageRoot()).toBe('/tmp/rdg-storage/private')
+    expect(getProtectedCustomerLicenseImageUrl('customer_1')).toBe('https://dashboard.rentaldrivego.test/dashboard/api/v1/customers/customer_1/license-image')
+  })
+
+  it('rejects implicit in-app storage in production', () => {
+    delete process.env.FILE_STORAGE_ROOT
+    process.env.NODE_ENV = 'production'
+
+    expect(() => assertStorageConfiguration()).toThrow('FILE_STORAGE_ROOT must be set in production')
+  })
+
+  it('uploads, resolves, and deletes files under the configured storage root', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rdg-storage-'))
+    process.env.FILE_STORAGE_ROOT = root
+    process.env.API_URL = 'https://api.rentaldrivego.test/'
+
+    const url = await uploadImage(Buffer.from('image-bytes'), 'customers/licenses', 'customer_1')
+
+    expect(url).toBe('https://api.rentaldrivego.test/storage/customers/licenses/customer_1.jpg')
+    const filePath = resolveStoredFilePath(url)
+    expect(filePath).toBe(path.join(root, 'private/customers/licenses/customer_1.jpg'))
+    expect(fs.readFileSync(filePath!, 'utf8')).toBe('image-bytes')
+
+    await deleteImage(url)
+    expect(fs.existsSync(filePath!)).toBe(false)
+  })
+
+  it('ignores non-storage URLs when resolving or deleting files', async () => {
+    process.env.FILE_STORAGE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'rdg-storage-'))
+
+    expect(resolveStoredFilePath('https://cdn.test/not-storage/file.jpg')).toBeNull()
+    await expect(deleteImage('https://cdn.test/not-storage/file.jpg')).resolves.toBeUndefined()
+  })
+})
@@ -0,0 +1,142 @@
+import fs from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+
+const APP_PACKAGE_ROOT = path.resolve(__dirname, '..', '..', '..')
+const APP_SOURCE_ROOT = path.join(APP_PACKAGE_ROOT, 'src')
+const APP_DIST_ROOT = path.join(APP_PACKAGE_ROOT, 'dist')
+const DEFAULT_STORAGE_ROOT = path.join(APP_PACKAGE_ROOT, 'storage')
+const LEGACY_STORAGE_ROOTS = [
+  path.join(APP_SOURCE_ROOT, 'lib', 'storage'),
+]
+
+export type StorageVisibility = 'public' | 'private'
+
+export function getStorageRoot(): string {
+  return process.env.FILE_STORAGE_ROOT
+    ? path.resolve(process.env.FILE_STORAGE_ROOT)
+    : DEFAULT_STORAGE_ROOT
+}
+
+export function getPublicStorageRoot(): string {
+  return path.join(getStorageRoot(), 'public')
+}
+
+export function getPrivateStorageRoot(): string {
+  return path.join(getStorageRoot(), 'private')
+}
+
+export function getLegacyStorageRoots(): string[] {
+  return LEGACY_STORAGE_ROOTS
+}
+
+function isWithinPath(targetPath: string, parentPath: string): boolean {
+  const relative = path.relative(parentPath, targetPath)
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+
+export function assertStorageConfiguration(): string {
+  const storageRoot = getStorageRoot()
+
+  if (process.env.NODE_ENV === 'production' && !process.env.FILE_STORAGE_ROOT) {
+    throw new Error('FILE_STORAGE_ROOT must be set in production so uploads are stored on the mounted volume.')
+  }
+
+  if (process.env.NODE_ENV === 'production') {
+    const forbiddenRoots = [APP_PACKAGE_ROOT, APP_SOURCE_ROOT, APP_DIST_ROOT]
+    const invalidRoot = forbiddenRoots.find((root) => isWithinPath(storageRoot, root))
+    if (invalidRoot) {
+      throw new Error(
+        `FILE_STORAGE_ROOT must point outside the API app tree in production. Received ${storageRoot}, which is inside ${invalidRoot}.`
+      )
+    }
+  }
+
+  return storageRoot
+}
+
+function ensureStorageRoot(visibility: StorageVisibility): string {
+  assertStorageConfiguration()
+  const root = visibility === 'public' ? getPublicStorageRoot() : getPrivateStorageRoot()
+  fs.mkdirSync(root, { recursive: true })
+  return root
+}
+
+function inferVisibility(folder: string): StorageVisibility {
+  const normalized = folder.replace(/\\/g, '/')
+  if (/\/customers\//.test(`/${normalized}/`)) return 'private'
+  if (/\/licenses?\//.test(`/${normalized}/`)) return 'private'
+  if (/\/contracts?\//.test(`/${normalized}/`)) return 'private'
+  if (/\/documents?\//.test(`/${normalized}/`)) return 'private'
+  if (/\/inspections?\//.test(`/${normalized}/`)) return 'private'
+  if (/\/internal\//.test(`/${normalized}/`)) return 'private'
+  return 'public'
+}
+
+function getApiBase(): string {
+  return (process.env.API_URL ?? 'http://localhost:4000').replace(/\/$/, '')
+}
+
+function getDashboardBase(): string {
+  return (
+    process.env.DASHBOARD_URL ??
+    process.env.NEXT_PUBLIC_DASHBOARD_URL ??
+    'http://localhost:3000/dashboard'
+  ).replace(/\/$/, '')
+}
+
+function getStorageRelativePath(imageUrl: string): string | null {
+  const marker = '/storage/'
+  const idx = imageUrl.indexOf(marker)
+  if (idx === -1) return null
+  return imageUrl.slice(idx + marker.length)
+}
+
+export function getProtectedCustomerLicenseImageUrl(customerId: string): string {
+  return `${getDashboardBase()}/api/v1/customers/${customerId}/license-image`
+}
+
+export async function uploadImage(
+  buffer: Buffer,
+  folder: string,
+  publicId?: string,
+  visibility: StorageVisibility = inferVisibility(folder),
+): Promise<string> {
+  const storageRoot = ensureStorageRoot(visibility)
+  const folderPath = path.join(storageRoot, folder)
+  if (!isWithinPath(folderPath, storageRoot)) {
+    throw new Error('Upload path escapes storage root')
+  }
+  fs.mkdirSync(folderPath, { recursive: true })
+
+  const filename = publicId
+    ? `${publicId}.jpg`
+    : `${crypto.randomBytes(16).toString('hex')}.jpg`
+
+  fs.writeFileSync(path.join(folderPath, filename), buffer)
+
+  return `${getApiBase()}/storage/${folder}/${filename}`
+}
+
+export function resolveStoredFilePath(imageUrl: string): string | null {
+  const relative = getStorageRelativePath(imageUrl)
+  if (!relative) return null
+
+  const roots = [getPublicStorageRoot(), getPrivateStorageRoot(), ...getLegacyStorageRoots(), assertStorageConfiguration()]
+  for (const root of roots) {
+    const filePath = path.join(root, relative)
+    if (!isWithinPath(filePath, root)) continue
+    if (fs.existsSync(filePath)) {
+      return filePath
+    }
+  }
+
+  return null
+}
+
+export async function deleteImage(imageUrl: string): Promise<void> {
+  const filePath = resolveStoredFilePath(imageUrl)
+  if (filePath && fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath)
+  }
+}
@@ -0,0 +1,155 @@
+import { z } from 'zod'
+import { sanitizeAndFormat, getMaxLength } from './inputValidation'
+import type { FieldType } from './inputValidation'
+
+// ─── Regex constants ───────────────────────────────────────────
+
+const GLOBAL_ALLOWED = /^[a-zA-Z0-9@\-/\s]*$/
+
+const EMAIL_REGEX = /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/
+
+/** Morocco phone: (+212|00212|0) + 5/6/7 + 8 digits (optional spaces) */
+const MA_PHONE_REGEX = /^(?:(?:\+|00)212|0)\s?[5-7](?:\s?\d){8}$/
+
+// ─── Phone sanitization ───────────────────────────────────────
+
+function sanitizePhone(raw: string): string {
+  let out = ''
+  for (const ch of raw) {
+    if (/[\d\s+]/.test(ch)) out += ch
+  }
+  return out.trim()
+}
+
+// ─── Required fields ───────────────────────────────────────────
+
+function applyFieldRules(fieldType: FieldType) {
+  const maxLength = getMaxLength(fieldType)
+  return z
+    .string()
+    .min(1, { message: 'This field is required' })
+    .trim()
+    .transform((val: string) => sanitizeAndFormat(val, fieldType))
+    .pipe(
+      z.string().refine(
+        (val: string) => val.length <= maxLength,
+        { message: 'Maximum ' + maxLength + ' characters allowed' }
+      )
+    )
+}
+
+// ─── Optional fields ───────────────────────────────────────────
+
+function applyOptionalFieldRules(fieldType: FieldType) {
+  const maxLength = getMaxLength(fieldType)
+  return z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (val === undefined || val === null || val.trim() === '') return undefined
+      return sanitizeAndFormat(val, fieldType)
+    })
+    .pipe(
+      z.string().optional().refine(
+        (val) => val === undefined || val.length <= maxLength,
+        { message: 'Maximum ' + maxLength + ' characters allowed' }
+      )
+    )
+}
+
+// ─── Exported helpers ──────────────────────────────────────────
+
+export function textField(fieldType: FieldType) {
+  return applyFieldRules(fieldType)
+}
+export function optionalTextField(fieldType: FieldType) {
+  return applyOptionalFieldRules(fieldType)
+}
+export function titleCaseAllField(fieldType: FieldType) {
+  return applyFieldRules(fieldType)
+}
+export function optionalTitleCaseAllField(fieldType: FieldType) {
+  return applyOptionalFieldRules(fieldType)
+}
+export function upperField(fieldType: FieldType) {
+  return applyFieldRules(fieldType)
+}
+export function optionalUpperField(fieldType: FieldType) {
+  return applyOptionalFieldRules(fieldType)
+}
+export function carTextField(fieldType: FieldType) {
+  return applyFieldRules(fieldType)
+}
+export function optionalCarTextField(fieldType: FieldType) {
+  return applyOptionalFieldRules(fieldType)
+}
+export function zipField() {
+  return applyFieldRules('zipCode')
+}
+export function optionalZipField() {
+  return applyOptionalFieldRules('zipCode')
+}
+
+// ─── Email fields ──────────────────────────────────────────────
+
+export function emailField() {
+  return z
+    .string()
+    .min(1, { message: 'Email is required' })
+    .trim()
+    .transform((val: string) => sanitizeAndFormat(val, 'email'))
+    .pipe(
+      z.string().refine(
+        (val: string) => EMAIL_REGEX.test(val),
+        { message: 'Please enter a valid email address' }
+      )
+    )
+}
+
+export function optionalEmailField() {
+  return z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (val === undefined || val === null || val.trim() === '') return undefined
+      return sanitizeAndFormat(val, 'email')
+    })
+    .pipe(
+      z.string().optional().refine(
+        (val) => val === undefined || EMAIL_REGEX.test(val),
+        { message: 'Please enter a valid email address' }
+      )
+    )
+}
+
+// ─── Phone fields ──────────────────────────────────────────────
+
+export function phoneField() {
+  return z
+    .string()
+    .min(1, { message: 'Phone number is required' })
+    .trim()
+    .transform((val: string) => sanitizePhone(val))
+    .pipe(
+      z.string().refine(
+        (val: string) => MA_PHONE_REGEX.test(val),
+        { message: 'Please enter a valid Morocco phone number' }
+      )
+    )
+}
+
+export function optionalPhoneField() {
+  return z
+    .string()
+    .optional()
+    .transform((val) => {
+      if (val === undefined || val === null || val.trim() === '') return undefined
+      return sanitizePhone(val)
+    })
+    .pipe(
+      z.string().optional().refine(
+        (val) => val === undefined || MA_PHONE_REGEX.test(val),
+        { message: 'Please enter a valid Morocco phone number' }
+      )
+    )
+}
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Request, Response } from 'express'
+
+import { getCookie, sendForbidden, sendPaymentRequired, sendUnauthorized } from './authHelpers'
+
+function responseStub() {
+  const res = {
+    status: vi.fn(),
+    json: vi.fn(),
+  }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('authHelpers', () => {
+  it('extracts and decodes a cookie value by name', () => {
+    const req = {
+      headers: {
+        cookie: 'theme=dark; employee_session=abc%20123%3D; other=value',
+      },
+    } as Request
+
+    expect(getCookie(req, 'employee_session')).toBe('abc 123=')
+  })
+
+  it('returns null when the cookie header or requested cookie is missing', () => {
+    expect(getCookie({ headers: {} } as Request, 'employee_session')).toBeNull()
+    expect(getCookie({ headers: { cookie: 'theme=dark' } } as Request, 'employee_session')).toBeNull()
+  })
+
+  it('sends a uniform unauthorized response', () => {
+    const res = responseStub()
+
+    sendUnauthorized(res, 'invalid_token', 'Invalid token')
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid token', statusCode: 401 })
+  })
+
+  it('sends forbidden responses with optional metadata', () => {
+    const res = responseStub()
+
+    sendForbidden(res, 'forbidden', 'Nope', { requiredRole: 'OWNER' })
+
+    expect(res.status).toHaveBeenCalledWith(403)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'forbidden',
+      message: 'Nope',
+      statusCode: 403,
+      requiredRole: 'OWNER',
+    })
+  })
+
+  it('sends payment-required responses with optional metadata', () => {
+    const res = responseStub()
+
+    sendPaymentRequired(res, 'subscription_suspended', 'Pay up', { billingUrl: '/billing' })
+
+    expect(res.status).toHaveBeenCalledWith(402)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'subscription_suspended',
+      message: 'Pay up',
+      statusCode: 402,
+      billingUrl: '/billing',
+    })
+  })
+})
@@ -0,0 +1,45 @@
+import { Request, Response } from 'express'
+
+/**
+ * Sends a uniform auth-error JSON response.
+ * All auth middleware must go through this function so the shape is identical
+ * to what the errorMiddleware produces for AppError instances.
+ */
+export function sendUnauthorized(res: Response, error: string, message: string) {
+  return res.status(401).json({ error, message, statusCode: 401 })
+}
+
+export function getCookie(req: Request, name: string): string | null {
+  const cookieHeader = req.headers.cookie
+  if (!cookieHeader) return null
+
+  for (const chunk of cookieHeader.split(';')) {
+    const [rawName, ...rawValue] = chunk.trim().split('=')
+    if (rawName === name) {
+      return decodeURIComponent(rawValue.join('='))
+    }
+  }
+
+  return null
+}
+
+export function getBearerToken(req: Request): string | null {
+  const authHeader = req.headers.authorization
+  if (!authHeader?.startsWith('Bearer ')) return null
+  const token = authHeader.slice(7).trim()
+  return token.length > 0 ? token : null
+}
+
+export function getAuthToken(req: Request, cookieName?: string): string | null {
+  // Prefer HttpOnly cookies over bearer tokens so stale script-readable tokens
+  // cannot shadow a valid server-managed session during migration.
+  return (cookieName ? getCookie(req, cookieName) : null) ?? getBearerToken(req)
+}
+
+export function sendForbidden(res: Response, error: string, message: string, extra?: Record<string, unknown>) {
+  return res.status(403).json({ error, message, statusCode: 403, ...extra })
+}
+
+export function sendPaymentRequired(res: Response, error: string, message: string, extra?: Record<string, unknown>) {
+  return res.status(402).json({ error, message, statusCode: 402, ...extra })
+}
@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const createdLimiters: any[] = []
+
+vi.mock('express-rate-limit', () => ({
+  default: vi.fn((config: any) => {
+    createdLimiters.push(config)
+    return config
+  }),
+  ipKeyGenerator: vi.fn((ip: string) => `ip:${ip}`),
+}))
+
+vi.mock('../security/tokens', () => ({
+  verifyAnyActorToken: vi.fn((token: string) => {
+    if (token === 'employee-token') return { type: 'employee', sub: 'employee_1' }
+    if (token === 'renter-token') return { type: 'renter', sub: 'renter_1' }
+    throw new Error('Invalid actor token')
+  }),
+}))
+
+import rateLimit, { ipKeyGenerator } from 'express-rate-limit'
+
+describe('rateLimiter middleware configuration', () => {
+  beforeEach(() => {
+    createdLimiters.length = 0
+    vi.resetModules()
+  })
+
+  it('configures auth limiter to count failed attempts only', async () => {
+    const { authLimiter } = await import('./rateLimiter')
+
+    expect(authLimiter.max).toBe(20)
+    expect(authLimiter.windowMs).toBe(15 * 60 * 1000)
+    expect(authLimiter.skipSuccessfulRequests).toBe(true)
+    expect(authLimiter.message).toMatchObject({ error: 'too_many_requests', statusCode: 429 })
+    expect(rateLimit).toHaveBeenCalled()
+  })
+
+  it('keys general API limits by verified actor identity before falling back to request context', async () => {
+    const { apiLimiter } = await import('./rateLimiter')
+
+    expect(apiLimiter.keyGenerator({
+      ip: '203.0.113.10',
+      headers: { cookie: 'theme=dark; employee_session=employee-token' },
+      companyId: 'company_1',
+    } as any)).toBe('ip:203.0.113.10:employee:employee_1')
+    expect(apiLimiter.keyGenerator({
+      ip: '203.0.113.10',
+      headers: { authorization: 'Bearer renter-token' },
+      renterId: 'legacy_renter_context',
+    } as any)).toBe('ip:203.0.113.10:renter:renter_1')
+    expect(apiLimiter.keyGenerator({
+      ip: '203.0.113.10',
+      headers: { authorization: 'Bearer invalid-token' },
+      companyId: 'company_1',
+    } as any)).toBe('ip:203.0.113.10:company_1')
+    expect(apiLimiter.keyGenerator({ ip: '203.0.113.10', headers: {}, renterId: 'renter_1' } as any)).toBe('ip:203.0.113.10:renter_1')
+    expect(ipKeyGenerator).toHaveBeenCalledWith('203.0.113.10')
+  })
+
+  it('uses tighter public and admin limits with explicit 429 payloads', async () => {
+    const { publicLimiter, adminLimiter } = await import('./rateLimiter')
+
+    expect(publicLimiter.max).toBe(60)
+    expect(publicLimiter.message.message).toBe('Rate limit exceeded')
+    expect(adminLimiter.max).toBe(100)
+    expect(adminLimiter.message.message).toBe('Too many admin requests')
+  })
+})
@@ -0,0 +1,126 @@
+import rateLimit, { ipKeyGenerator } from 'express-rate-limit'
+import type { Request } from 'express'
+import { verifyAnyActorToken } from '../security/tokens'
+import { getSessionCookieName } from '../security/sessionCookies'
+
+
+const SESSION_COOKIE_NAMES = [
+  getSessionCookieName('admin'),
+  getSessionCookieName('employee'),
+  getSessionCookieName('renter'),
+]
+
+function readCookie(cookieHeader: string | undefined, name: string): string | null {
+  if (!cookieHeader) return null
+
+  for (const chunk of cookieHeader.split(';')) {
+    const [rawName, ...rawValue] = chunk.trim().split('=')
+    if (rawName === name) return decodeURIComponent(rawValue.join('='))
+  }
+
+  return null
+}
+
+function getBearerToken(req: Request): string | null {
+  const authHeader = req.headers.authorization
+  if (!authHeader?.startsWith('Bearer ')) return null
+  const token = authHeader.slice(7).trim()
+  return token || null
+}
+
+function getRequestToken(req: Request): string | null {
+  const cookieHeader = req.headers.cookie
+  for (const name of SESSION_COOKIE_NAMES) {
+    const token = readCookie(cookieHeader, name)
+    if (token) return token
+  }
+
+  return getBearerToken(req)
+}
+
+function getAuthenticatedActorKey(req: Request): string | null {
+  const token = getRequestToken(req)
+  if (!token) return null
+
+  try {
+    const payload = verifyAnyActorToken(token)
+    return `${payload.type}:${payload.sub}`
+  } catch {
+    return null
+  }
+}
+
+// req.ip is already the real client IP when app.set('trust proxy', 1) is configured
+const getClientIpKey = (req: Request) => ipKeyGenerator(req.ip ?? '')
+
+// Strict limiter for auth endpoints — prevents brute-force and credential stuffing.
+// Successful requests (e.g. GET /me profile reads) are skipped so only failed
+// attempts count toward the cap.
+export const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 20,
+  standardHeaders: 'draft-7',
+  legacyHeaders: false,
+  skipSuccessfulRequests: true,
+  keyGenerator: (req) => getClientIpKey(req),
+  message: { error: 'too_many_requests', message: 'Too many attempts, please try again later', statusCode: 429 },
+})
+
+// Standard limiter for general authenticated API endpoints
+export const apiLimiter = rateLimit({
+  windowMs: 60 * 1000, // 1 minute
+  max: 120,
+  standardHeaders: 'draft-7',
+  legacyHeaders: false,
+  keyGenerator: (req) => {
+    const ip = getClientIpKey(req)
+    const actorKey = getAuthenticatedActorKey(req)
+    const companyId = (req as any).companyId ?? ''
+    const renterId = (req as any).renterId ?? ''
+    return `${ip}:${actorKey || companyId || renterId || 'anonymous'}`
+  },
+  message: { error: 'too_many_requests', message: 'Rate limit exceeded', statusCode: 429 },
+})
+
+// Limiter for public marketplace and site endpoints (no auth)
+export const publicLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  max: 60,
+  standardHeaders: 'draft-7',
+  legacyHeaders: false,
+  keyGenerator: (req) => getClientIpKey(req),
+  message: { error: 'too_many_requests', message: 'Rate limit exceeded', statusCode: 429 },
+})
+
+// Tight limiter for admin endpoints
+export const adminLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  standardHeaders: 'draft-7',
+  legacyHeaders: false,
+  keyGenerator: (req) => {
+    const ip = getClientIpKey(req)
+    return `${ip}:${getAuthenticatedActorKey(req) || 'anonymous'}`
+  },
+  message: { error: 'too_many_requests', message: 'Too many admin requests', statusCode: 429 },
+})
+
+
+// Applied after authentication so limits can include actor identity rather than
+// pretending every employee behind the same NAT is the same organism.
+export const actorLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  max: 240,
+  standardHeaders: 'draft-7',
+  legacyHeaders: false,
+  keyGenerator: (req) => {
+    const ip = getClientIpKey(req)
+    const actorKey = getAuthenticatedActorKey(req)
+    const companyId = (req as any).companyId ?? ''
+    const employeeId = (req as any).employee?.id ?? ''
+    const renterId = (req as any).renterId ?? ''
+    const adminId = (req as any).admin?.id ?? ''
+    return `${ip}:${companyId}:${actorKey || employeeId || renterId || adminId || 'anonymous'}`
+  },
+  message: { error: 'too_many_requests', message: 'Authenticated rate limit exceeded', statusCode: 429 },
+})
@@ -0,0 +1,10 @@
+import crypto from 'crypto'
+import type { Request, Response, NextFunction } from 'express'
+
+export function requestIdMiddleware(req: Request, res: Response, next: NextFunction) {
+  const incoming = req.headers['x-request-id']
+  const requestId = Array.isArray(incoming) ? incoming[0] : incoming
+  req.requestId = requestId && requestId.length <= 128 ? requestId : `req_${crypto.randomUUID()}`
+  res.setHeader('X-Request-Id', req.requestId)
+  next()
+}
@@ -0,0 +1,152 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+vi.mock('jsonwebtoken', () => ({
+  default: { verify: vi.fn() },
+}))
+
+vi.mock('../lib/prisma', () => ({
+  prisma: {
+    adminUser: { findUnique: vi.fn() },
+  },
+}))
+
+import jwt from 'jsonwebtoken'
+import { prisma } from '../lib/prisma'
+import { requireAdminAuth, requireAdminRole } from './requireAdminAuth'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireAdminAuth middleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    process.env.JWT_SECRET = 'test-secret'
+  })
+
+  it('rejects requests without an admin bearer token', async () => {
+    const req = { headers: {} } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Admin authentication required', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects invalid token signatures', async () => {
+    vi.mocked(jwt.verify).mockImplementation(() => { throw new Error('bad token') })
+    const req = { headers: { authorization: 'Bearer bad' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid or expired admin token', statusCode: 401 })
+    expect(prisma.adminUser.findUnique).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-admin token types', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'emp_1', type: 'employee' } as any)
+    const req = { headers: { authorization: 'Bearer employee-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid or expired admin token', statusCode: 401 })
+    expect(prisma.adminUser.findUnique).not.toHaveBeenCalled()
+  })
+
+  it('rejects inactive admin accounts', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'admin_1', type: 'admin' } as any)
+    vi.mocked(prisma.adminUser.findUnique).mockResolvedValue({ id: 'admin_1', isActive: false } as any)
+    const req = { headers: { authorization: 'Bearer admin-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Admin account not found or deactivated', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('attaches the admin record for valid admin tokens', async () => {
+    const admin = { id: 'admin_1', isActive: true, role: 'SUPPORT', totpEnabled: true }
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'admin_1', type: 'admin' } as any)
+    vi.mocked(prisma.adminUser.findUnique).mockResolvedValue(admin as any)
+    const req = { headers: { authorization: 'Bearer admin-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(prisma.adminUser.findUnique).toHaveBeenCalledWith({ where: { id: 'admin_1' } })
+    expect(req.admin).toEqual(admin)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  it('blocks non-enrolled admins from privileged routes', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'admin_1', type: 'admin' } as any)
+    vi.mocked(prisma.adminUser.findUnique).mockResolvedValue({ id: 'admin_1', isActive: true, role: 'ADMIN', totpEnabled: false } as any)
+    const req = { headers: { authorization: 'Bearer admin-token' }, path: '/companies' } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireAdminAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(403)
+    expect(res.json).toHaveBeenCalledWith({ error: 'admin_2fa_required', message: 'Admin 2FA enrollment is required before using privileged admin routes', statusCode: 403 })
+    expect(next).not.toHaveBeenCalled()
+  })
+})
+
+describe('requireAdminRole middleware', () => {
+  it('requires requireAdminAuth to run first', () => {
+    const req = {} as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireAdminRole('SUPPORT' as any)(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Admin authentication required', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('blocks admins below the required rank', () => {
+    const req = { admin: { role: 'VIEWER' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireAdminRole('FINANCE' as any)(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(403)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'forbidden',
+      message: 'This action requires the FINANCE role or higher',
+      statusCode: 403,
+    })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('allows admins at or above the required rank', () => {
+    const req = { admin: { role: 'ADMIN' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireAdminRole('SUPPORT' as any)(req, res, next)
+
+    expect(next).toHaveBeenCalledTimes(1)
+    expect(res.status).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,94 @@
+import { Request, Response, NextFunction } from 'express'
+import { prisma } from '../lib/prisma'
+import { AdminRole } from '@rentaldrivego/database'
+import { getAuthToken, sendUnauthorized, sendForbidden } from './authHelpers'
+import { verifyActorToken } from '../security/tokens'
+import { getSessionCookieName } from '../security/sessionCookies'
+
+const ROLE_RANK: Record<AdminRole, number> = {
+  SUPER_ADMIN: 5,
+  ADMIN:       4,
+  SUPPORT:     3,
+  FINANCE:     2,
+  VIEWER:      1,
+}
+
+const ADMIN_2FA_ENROLLMENT_EXEMPT_PATHS = new Set([
+  '/auth/me',
+  '/auth/logout',
+  '/auth/2fa/setup',
+  '/auth/2fa/verify',
+])
+
+const FRESH_2FA_WINDOW_MS = Number(process.env.ADMIN_FRESH_2FA_WINDOW_MS ?? 10 * 60 * 1000)
+
+function is2faEnrollmentExempt(req: Request) {
+  return ADMIN_2FA_ENROLLMENT_EXEMPT_PATHS.has(req.path)
+}
+
+/**
+ * Requires a valid admin session token.
+ *
+ * Guarantees on success:
+ *   req.admin — the full AdminUser record
+ */
+export async function requireAdminAuth(req: Request, res: Response, next: NextFunction) {
+  const token = getAuthToken(req, getSessionCookieName('admin'))
+
+  if (!token) return sendUnauthorized(res, 'unauthenticated', 'Admin authentication required')
+
+  let payload: { sub: string; type: string; last2faAt?: number }
+  try {
+    payload = verifyActorToken(token, 'admin')
+  } catch {
+    return sendUnauthorized(res, 'invalid_token', 'Invalid or expired admin token')
+  }
+
+  const admin = await prisma.adminUser.findUnique({ where: { id: payload.sub } })
+  if (!admin || !admin.isActive) {
+    return sendUnauthorized(res, 'unauthenticated', 'Admin account not found or deactivated')
+  }
+
+  if (!admin.totpEnabled && !is2faEnrollmentExempt(req)) {
+    return sendForbidden(res, 'admin_2fa_required', 'Admin 2FA enrollment is required before using privileged admin routes')
+  }
+
+  req.admin = admin
+  req.adminAuthLast2faAt = typeof payload.last2faAt === 'number' ? payload.last2faAt : undefined
+  next()
+}
+
+/**
+ * Requires the authenticated admin to have at least `minimumRole`.
+ * Must be applied after `requireAdminAuth`.
+ */
+export function requireAdminRole(minimumRole: AdminRole) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const admin = req.admin
+    if (!admin) return sendUnauthorized(res, 'unauthenticated', 'Admin authentication required')
+
+    const rank     = ROLE_RANK[admin.role]   ?? 0
+    const required = ROLE_RANK[minimumRole]  ?? 99
+
+    if (rank < required) {
+      return sendForbidden(res, 'forbidden', `This action requires the ${minimumRole} role or higher`)
+    }
+
+    next()
+  }
+}
+
+export function requireFreshAdmin2FA(req: Request, res: Response, next: NextFunction) {
+  const admin = req.admin
+  if (!admin) return sendUnauthorized(res, 'unauthenticated', 'Admin authentication required')
+  if (!admin.totpEnabled) {
+    return sendForbidden(res, 'admin_2fa_required', 'Admin 2FA enrollment is required for this action')
+  }
+
+  const last2faAt = req.adminAuthLast2faAt
+  if (!last2faAt || Date.now() - last2faAt > FRESH_2FA_WINDOW_MS) {
+    return sendForbidden(res, 'fresh_2fa_required', 'Fresh admin 2FA verification is required for this action')
+  }
+
+  next()
+}
@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+import { generateCompanyApiKey } from '../security/apiKeys'
+
+vi.mock('../lib/prisma', () => ({
+  prisma: {
+    companyApiKey: {
+      findUnique: vi.fn(),
+      update: vi.fn(),
+    },
+  },
+}))
+
+import { prisma } from '../lib/prisma'
+import { requireApiKey } from './requireApiKey'
+
+function createResponseStub() {
+  const res = {
+    status: vi.fn(),
+    json: vi.fn(),
+  }
+
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+
+  return res as unknown as Response & typeof res
+}
+
+describe('requireApiKey middleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('rejects requests with no x-api-key header', async () => {
+    const req = { headers: {} } as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'missing_api_key',
+      message: 'API key required in x-api-key header',
+      statusCode: 401,
+    })
+    expect((prisma as any).companyApiKey.findUnique).not.toHaveBeenCalled()
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects malformed API keys before database lookup', async () => {
+    const req = { headers: { 'x-api-key': 'bad-key' } } as unknown as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect((prisma as any).companyApiKey.findUnique).not.toHaveBeenCalled()
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'invalid_api_key',
+      message: 'Invalid API key',
+      statusCode: 401,
+    })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects unknown API key prefixes', async () => {
+    const generated = generateCompanyApiKey()
+    vi.mocked((prisma as any).companyApiKey.findUnique).mockResolvedValue(null)
+    const req = { headers: { 'x-api-key': generated.rawKey } } as unknown as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect((prisma as any).companyApiKey.findUnique).toHaveBeenCalledWith({
+      where: { prefix: generated.prefix },
+      include: { company: true },
+    })
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'invalid_api_key',
+      message: 'Invalid API key',
+      statusCode: 401,
+    })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects revoked API keys', async () => {
+    const generated = generateCompanyApiKey()
+    vi.mocked((prisma as any).companyApiKey.findUnique).mockResolvedValue({
+      id: 'key_1',
+      companyId: 'company_1',
+      prefix: generated.prefix,
+      keyHash: generated.keyHash,
+      revokedAt: new Date('2026-06-01T00:00:00.000Z'),
+      company: { id: 'company_1', name: 'Atlas Cars' },
+    })
+    const req = { headers: { 'x-api-key': generated.rawKey } } as unknown as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects API keys whose secret does not match the stored hash', async () => {
+    const generated = generateCompanyApiKey()
+    const other = generateCompanyApiKey()
+    vi.mocked((prisma as any).companyApiKey.findUnique).mockResolvedValue({
+      id: 'key_1',
+      companyId: 'company_1',
+      prefix: generated.prefix,
+      keyHash: other.keyHash,
+      revokedAt: null,
+      company: { id: 'company_1', name: 'Atlas Cars' },
+    })
+    const req = { headers: { 'x-api-key': generated.rawKey } } as unknown as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('attaches company context, updates lastUsedAt, and calls next for valid API keys', async () => {
+    const generated = generateCompanyApiKey()
+    const company = { id: 'company_1', name: 'Atlas Cars' }
+    vi.mocked((prisma as any).companyApiKey.findUnique).mockResolvedValue({
+      id: 'key_1',
+      companyId: company.id,
+      prefix: generated.prefix,
+      keyHash: generated.keyHash,
+      revokedAt: null,
+      company,
+    })
+    vi.mocked((prisma as any).companyApiKey.update).mockResolvedValue({})
+    const req = { headers: { 'x-api-key': generated.rawKey } } as unknown as Request
+    const res = createResponseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireApiKey(req, res, next)
+
+    expect((prisma as any).companyApiKey.update).toHaveBeenCalledWith({
+      where: { id: 'key_1' },
+      data: { lastUsedAt: expect.any(Date) },
+    })
+    expect(req.company).toEqual(company)
+    expect(req.companyId).toBe('company_1')
+    expect(next).toHaveBeenCalledTimes(1)
+    expect(res.status).not.toHaveBeenCalled()
+    expect(res.json).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,35 @@
+import { Request, Response, NextFunction } from 'express'
+import { prisma } from '../lib/prisma'
+import { getApiKeyPrefix, hashApiKey, timingSafeEqualHex } from '../security/apiKeys'
+
+export async function requireApiKey(req: Request, res: Response, next: NextFunction) {
+  const apiKey = req.headers['x-api-key'] as string | undefined
+
+  if (!apiKey) {
+    return res.status(401).json({ error: 'missing_api_key', message: 'API key required in x-api-key header', statusCode: 401 })
+  }
+
+  const prefix = getApiKeyPrefix(apiKey)
+  if (!prefix) {
+    return res.status(401).json({ error: 'invalid_api_key', message: 'Invalid API key', statusCode: 401 })
+  }
+
+  const keyRecord = await (prisma as any).companyApiKey.findUnique({
+    where: { prefix },
+    include: { company: true },
+  })
+
+  const hashed = hashApiKey(apiKey)
+  if (!keyRecord || keyRecord.revokedAt || !timingSafeEqualHex(hashed, keyRecord.keyHash)) {
+    return res.status(401).json({ error: 'invalid_api_key', message: 'Invalid API key', statusCode: 401 })
+  }
+
+  await (prisma as any).companyApiKey.update({
+    where: { id: keyRecord.id },
+    data: { lastUsedAt: new Date() },
+  })
+
+  req.company = keyRecord.company
+  req.companyId = keyRecord.companyId
+  next()
+}
@@ -0,0 +1,119 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+vi.mock('jsonwebtoken', () => ({
+  default: { verify: vi.fn() },
+}))
+
+vi.mock('../lib/prisma', () => ({
+  prisma: {
+    employee: { findUnique: vi.fn() },
+  },
+}))
+
+import jwt from 'jsonwebtoken'
+import { prisma } from '../lib/prisma'
+import { requireCompanyAuth, requireCompanyDocumentAuth } from './requireCompanyAuth'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireCompanyAuth middleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    process.env.JWT_SECRET = 'test-secret'
+  })
+
+  it('rejects missing bearer tokens', async () => {
+    const req = { headers: {} } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Authentication required', statusCode: 401 })
+    expect(prisma.employee.findUnique).not.toHaveBeenCalled()
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects invalid tokens', async () => {
+    vi.mocked(jwt.verify).mockImplementation(() => { throw new Error('bad token') })
+    const req = { headers: { authorization: 'Bearer bad' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid or expired session token', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-employee token types', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'renter_1', type: 'renter' } as any)
+    const req = { headers: { authorization: 'Bearer renter-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid or expired session token', statusCode: 401 })
+    expect(prisma.employee.findUnique).not.toHaveBeenCalled()
+  })
+
+  it('rejects inactive or missing employees', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'emp_1', type: 'employee' } as any)
+    vi.mocked(prisma.employee.findUnique).mockResolvedValue({ id: 'emp_1', isActive: false } as any)
+    const req = { headers: { authorization: 'Bearer employee-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Employee account not found or inactive', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('attaches employee and company context for active employees', async () => {
+    const employee = { id: 'emp_1', companyId: 'company_1', isActive: true, company: { id: 'company_1', name: 'Atlas' } }
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'emp_1', type: 'employee' } as any)
+    vi.mocked(prisma.employee.findUnique).mockResolvedValue(employee as any)
+    const req = { headers: { authorization: 'Bearer employee-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyAuth(req, res, next)
+
+    expect(prisma.employee.findUnique).toHaveBeenCalledWith({ where: { id: 'emp_1' }, include: { company: true } })
+    expect(req.employee).toEqual(employee)
+    expect(req.company).toEqual(employee.company)
+    expect(req.companyId).toBe('company_1')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  it('accepts employee_session cookies for document routes', async () => {
+    const employee = { id: 'emp_2', companyId: 'company_2', isActive: true, company: { id: 'company_2' } }
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'emp_2', type: 'employee' } as any)
+    vi.mocked(prisma.employee.findUnique).mockResolvedValue(employee as any)
+    const req = { headers: { cookie: 'employee_session=cookie-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireCompanyDocumentAuth(req, res, next)
+
+    expect(jwt.verify).toHaveBeenCalledWith('cookie-token', 'test-secret', {
+      algorithms: ['HS256'],
+      issuer: 'rentaldrivego-api',
+      audience: 'employee',
+    })
+    expect(req.companyId).toBe('company_2')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})
@@ -0,0 +1,49 @@
+import { Request, Response, NextFunction } from 'express'
+import { prisma } from '../lib/prisma'
+import { getAuthToken, sendUnauthorized } from './authHelpers'
+import { verifyActorToken } from '../security/tokens'
+import { getSessionCookieName } from '../security/sessionCookies'
+import { actorLimiter } from './rateLimiter'
+
+/**
+ * Validates a company-scoped Bearer token and loads the employee + company onto `req`.
+ *
+ * Guarantees on success:
+ *   req.employee  — full employee record (with company relation)
+ *   req.company   — the employee's company
+ *   req.companyId — string shorthand for req.company.id
+ */
+async function authenticateCompanyRequest(req: Request, res: Response, next: NextFunction) {
+  const token = getAuthToken(req, getSessionCookieName('employee'))
+
+  if (!token) return sendUnauthorized(res, 'unauthenticated', 'Authentication required')
+
+  let payload: { sub: string; type: string }
+  try {
+    payload = verifyActorToken(token, 'employee')
+  } catch {
+    return sendUnauthorized(res, 'invalid_token', 'Invalid or expired session token')
+  }
+
+  const employee = await prisma.employee.findUnique({
+    where: { id: payload.sub },
+    include: { company: true },
+  })
+
+  if (!employee || !employee.isActive) {
+    return sendUnauthorized(res, 'unauthenticated', 'Employee account not found or inactive')
+  }
+
+  req.employee  = employee
+  req.company   = employee.company
+  req.companyId = employee.companyId
+  return actorLimiter(req, res, next)
+}
+
+export async function requireCompanyAuth(req: Request, res: Response, next: NextFunction) {
+  return authenticateCompanyRequest(req, res, next)
+}
+
+export async function requireCompanyDocumentAuth(req: Request, res: Response, next: NextFunction) {
+  return authenticateCompanyRequest(req, res, next)
+}
@@ -0,0 +1,22 @@
+import type { Request, Response, NextFunction } from 'express'
+import { sendForbidden, sendUnauthorized } from './authHelpers'
+import type { EmployeeRole } from '@rentaldrivego/database'
+import { CompanyPolicy, type CompanyPolicyAction } from '../security/policies/companyPolicy'
+
+export function requireCompanyPolicy(action: CompanyPolicyAction) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const employee = req.employee
+    if (!employee) return sendUnauthorized(res, 'unauthenticated', 'Authentication required')
+
+    const allowedRoles: readonly EmployeeRole[] = CompanyPolicy[action]
+    if (!allowedRoles.includes(employee.role)) {
+      return sendForbidden(res, 'forbidden', 'You do not have permission to perform this action', {
+        action,
+        allowedRoles,
+        yourRole: employee.role,
+      })
+    }
+
+    next()
+  }
+}
@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+vi.mock('jsonwebtoken', () => ({
+  default: { verify: vi.fn() },
+}))
+
+vi.mock('../lib/prisma', () => ({
+  prisma: {
+    renter: { findUnique: vi.fn() },
+  },
+}))
+
+import jwt from 'jsonwebtoken'
+import { prisma } from '../lib/prisma'
+import { optionalRenterAuth, requireRenterAuth } from './requireRenterAuth'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireRenterAuth middleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    process.env.JWT_SECRET = 'test-secret'
+  })
+
+  it('rejects missing bearer tokens', async () => {
+    const req = { headers: {} } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireRenterAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Renter authentication required', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects invalid tokens and wrong token types', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'emp_1', type: 'employee' } as any)
+    const req = { headers: { authorization: 'Bearer employee-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireRenterAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'invalid_token', message: 'Invalid or expired token', statusCode: 401 })
+    expect(prisma.renter.findUnique).not.toHaveBeenCalled()
+  })
+
+  it('rejects inactive renters', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'renter_1', type: 'renter' } as any)
+    vi.mocked(prisma.renter.findUnique).mockResolvedValue({ id: 'renter_1', isActive: false } as any)
+    const req = { headers: { authorization: 'Bearer renter-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireRenterAuth(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Renter account not found or inactive', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('attaches renterId for active renters', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'renter_1', type: 'renter' } as any)
+    vi.mocked(prisma.renter.findUnique).mockResolvedValue({ id: 'renter_1', isActive: true } as any)
+    const req = { headers: { authorization: 'Bearer renter-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireRenterAuth(req, res, next)
+
+    expect(req.renterId).toBe('renter_1')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+
+  it('optional auth never blocks missing or invalid tokens', async () => {
+    const noTokenReq = { headers: {} } as Request
+    const invalidReq = { headers: { authorization: 'Bearer bad' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+    vi.mocked(jwt.verify).mockImplementation(() => { throw new Error('bad token') })
+
+    await optionalRenterAuth(noTokenReq, res, next)
+    await optionalRenterAuth(invalidReq, res, next)
+
+    expect(next).toHaveBeenCalledTimes(2)
+  })
+
+  it('optional auth attaches renterId only for renter tokens', async () => {
+    vi.mocked(jwt.verify).mockReturnValue({ sub: 'renter_2', type: 'renter' } as any)
+    const req = { headers: { authorization: 'Bearer renter-token' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await optionalRenterAuth(req, res, next)
+
+    expect(req.renterId).toBe('renter_2')
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})
@@ -0,0 +1,54 @@
+import { Request, Response, NextFunction } from 'express'
+import { prisma } from '../lib/prisma'
+import { getAuthToken, sendUnauthorized } from './authHelpers'
+import { verifyActorToken } from '../security/tokens'
+import { getSessionCookieName } from '../security/sessionCookies'
+import { actorLimiter } from './rateLimiter'
+
+/**
+ * Requires a valid renter Bearer token.
+ *
+ * Guarantees on success:
+ *   req.renterId — the authenticated renter's id
+ */
+export async function requireRenterAuth(req: Request, res: Response, next: NextFunction) {
+  const token = getAuthToken(req, getSessionCookieName('renter'))
+
+  if (!token) return sendUnauthorized(res, 'unauthenticated', 'Renter authentication required')
+
+  let payload: { sub: string; type: string }
+  try {
+    payload = verifyActorToken(token, 'renter')
+  } catch {
+    return sendUnauthorized(res, 'invalid_token', 'Invalid or expired token')
+  }
+
+  const renter = await prisma.renter.findUnique({ where: { id: payload.sub } })
+  if (!renter || !renter.isActive) {
+    return sendUnauthorized(res, 'unauthenticated', 'Renter account not found or inactive')
+  }
+
+  req.renterId = renter.id
+  return actorLimiter(req, res, next)
+}
+
+/**
+ * Optionally extracts renter identity from a Bearer token.
+ * Never blocks the request — invalid or absent tokens are silently ignored.
+ *
+ * Sets on success:
+ *   req.renterId — the authenticated renter's id (if token is valid)
+ */
+export async function optionalRenterAuth(req: Request, _res: Response, next: NextFunction) {
+  const token = getAuthToken(req, getSessionCookieName('renter'))
+  if (!token) return next()
+
+  try {
+    const payload = verifyActorToken(token, 'renter')
+    req.renterId = payload.sub
+  } catch {
+    // Optional — silently ignore invalid tokens
+  }
+
+  next()
+}
@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+import { requireRole } from './requireRole'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireRole middleware', () => {
+  it('rejects requests when company auth did not attach an employee', () => {
+    const req = {} as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireRole('AGENT' as any)(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'Authentication required', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('rejects employees below the required role and includes role context', () => {
+    const req = { employee: { role: 'AGENT' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireRole('MANAGER' as any)(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(403)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'forbidden',
+      message: 'This action requires the MANAGER role or higher',
+      statusCode: 403,
+      requiredRole: 'MANAGER',
+      yourRole: 'AGENT',
+    })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('allows employees at or above the required role', () => {
+    const req = { employee: { role: 'OWNER' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireRole('MANAGER' as any)(req, res, next)
+
+    expect(next).toHaveBeenCalledTimes(1)
+    expect(res.status).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,32 @@
+import { Request, Response, NextFunction } from 'express'
+import { EmployeeRole } from '@rentaldrivego/database'
+import { sendUnauthorized, sendForbidden } from './authHelpers'
+
+const ROLE_RANK: Record<EmployeeRole, number> = {
+  OWNER:   3,
+  MANAGER: 2,
+  AGENT:   1,
+}
+
+/**
+ * Requires the authenticated employee to have at least `minimumRole`.
+ * Must be applied after `requireCompanyAuth`.
+ */
+export function requireRole(minimumRole: EmployeeRole) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const employee = req.employee
+    if (!employee) return sendUnauthorized(res, 'unauthenticated', 'Authentication required')
+
+    const employeeRank = ROLE_RANK[employee.role] ?? 0
+    const requiredRank = ROLE_RANK[minimumRole]   ?? 99
+
+    if (employeeRank < requiredRank) {
+      return sendForbidden(res, 'forbidden', `This action requires the ${minimumRole} role or higher`, {
+        requiredRole: minimumRole,
+        yourRole: employee.role,
+      })
+    }
+
+    next()
+  }
+}
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+import { requireSubscription } from './requireSubscription'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireSubscription middleware', () => {
+  beforeEach(() => {
+    process.env.NEXT_PUBLIC_DASHBOARD_URL = 'https://dashboard.example.test'
+  })
+
+  it('requires tenant/company context first', () => {
+    const req = {} as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireSubscription(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'unauthenticated', message: 'No company context', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('blocks suspended companies with a billing URL', () => {
+    const req = { company: { status: 'SUSPENDED' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireSubscription(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(402)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'subscription_suspended',
+      message: 'Your account has been suspended. Please contact support or renew your subscription.',
+      statusCode: 402,
+      billingUrl: 'https://dashboard.example.test/billing',
+    })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('blocks pending companies with setup guidance', () => {
+    const req = { company: { status: 'PENDING' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireSubscription(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(402)
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      error: 'subscription_pending',
+      message: 'Your account is pending activation. Please complete your subscription setup.',
+    }))
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('allows active companies through', () => {
+    const req = { company: { status: 'ACTIVE' } } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    requireSubscription(req, res, next)
+
+    expect(next).toHaveBeenCalledTimes(1)
+    expect(res.status).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express'
+import { sendUnauthorized, sendPaymentRequired } from './authHelpers'
+
+const BLOCKED_STATUSES = ['SUSPENDED', 'PENDING']
+
+/**
+ * Blocks requests for companies with lapsed or unactivated subscriptions.
+ * Must be applied after `requireTenant`.
+ *
+ * Guarantees on success:
+ *   req.company.status is not SUSPENDED or PENDING
+ */
+export function requireSubscription(req: Request, res: Response, next: NextFunction) {
+  const company = req.company
+  if (!company) return sendUnauthorized(res, 'unauthenticated', 'No company context')
+
+  if (BLOCKED_STATUSES.includes(company.status)) {
+    return sendPaymentRequired(
+      res,
+      `subscription_${company.status.toLowerCase()}`,
+      company.status === 'SUSPENDED'
+        ? 'Your account has been suspended. Please contact support or renew your subscription.'
+        : 'Your account is pending activation. Please complete your subscription setup.',
+      { billingUrl: `${process.env.NEXT_PUBLIC_DASHBOARD_URL}/billing` },
+    )
+  }
+
+  next()
+}
@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { NextFunction, Request, Response } from 'express'
+
+vi.mock('../lib/prisma', () => ({
+  prisma: {
+    company: { findUnique: vi.fn() },
+  },
+}))
+
+import { prisma } from '../lib/prisma'
+import { requireTenant } from './requireTenant'
+
+function responseStub() {
+  const res = { status: vi.fn(), json: vi.fn() }
+  res.status.mockReturnValue(res)
+  res.json.mockReturnValue(res)
+  return res as unknown as Response & typeof res
+}
+
+describe('requireTenant middleware', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('fails fast when company auth did not set companyId', async () => {
+    const req = {} as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireTenant(req, res, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({
+      error: 'unauthenticated',
+      message: 'Tenant context missing — requireCompanyAuth must run first',
+      statusCode: 401,
+    })
+    expect(prisma.company.findUnique).not.toHaveBeenCalled()
+  })
+
+  it('rejects company ids that no longer exist', async () => {
+    vi.mocked(prisma.company.findUnique).mockResolvedValue(null)
+    const req = { companyId: 'company_missing' } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireTenant(req, res, next)
+
+    expect(prisma.company.findUnique).toHaveBeenCalledWith({ where: { id: 'company_missing' } })
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(res.json).toHaveBeenCalledWith({ error: 'company_not_found', message: 'Company not found', statusCode: 401 })
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('attaches the fresh company record and continues', async () => {
+    const company = { id: 'company_1', status: 'ACTIVE' }
+    vi.mocked(prisma.company.findUnique).mockResolvedValue(company as any)
+    const req = { companyId: 'company_1' } as Request
+    const res = responseStub()
+    const next = vi.fn() as NextFunction
+
+    await requireTenant(req, res, next)
+
+    expect(req.company).toEqual(company)
+    expect(next).toHaveBeenCalledTimes(1)
+  })
+})
@@ -0,0 +1,25 @@
+import { Request, Response, NextFunction } from 'express'
+import { prisma } from '../lib/prisma'
+import { sendUnauthorized } from './authHelpers'
+
+/**
+ * Loads the company record and validates it exists.
+ * Must be applied after `requireCompanyAuth`.
+ *
+ * Guarantees on success:
+ *   req.company   — full Company record
+ *   req.companyId — string id (already set by requireCompanyAuth)
+ */
+export async function requireTenant(req: Request, res: Response, next: NextFunction) {
+  if (!req.companyId) {
+    return sendUnauthorized(res, 'unauthenticated', 'Tenant context missing — requireCompanyAuth must run first')
+  }
+
+  const company = await prisma.company.findUnique({ where: { id: req.companyId } })
+  if (!company) {
+    return sendUnauthorized(res, 'company_not_found', 'Company not found')
+  }
+
+  req.company = company
+  next()
+}
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import {
+  billingAccountUpdateSchema,
+  billingCreditNoteSchema,
+  billingRefundSchema,
+  createBillingInvoiceSchema,
+  payBillingInvoiceSchema,
+} from './admin.schemas'
+
+describe('admin billing schemas', () => {
+  it('accepts complete draft invoice payloads and preserves nullable billing fields', () => {
+    const parsed = createBillingInvoiceSchema.parse({
+      subscriptionId: null,
+      invoiceType: 'MANUAL',
+      currency: 'MAD',
+      dueAt: '2026-08-10',
+      isSubscriptionBlocking: false,
+      adminReason: null,
+      lineItems: [{
+        type: 'MANUAL_ADJUSTMENT',
+        description: 'Manual correction',
+        quantity: 2,
+        unitAmount: 1500,
+        periodStart: null,
+        periodEnd: '2026-08-31T00:00:00.000Z',
+      }],
+    })
+
+    expect(parsed.lineItems[0]).toMatchObject({ quantity: 2, unitAmount: 1500, periodStart: null })
+  })
+
+  it('rejects invoices without line items because empty invoices are bookkeeping cosplay', () => {
+    expect(() => createBillingInvoiceSchema.parse({ invoiceType: 'MANUAL', lineItems: [] })).toThrow()
+  })
+
+  it('bounds billing account net terms and validates email formatting', () => {
+    expect(billingAccountUpdateSchema.parse({
+      legalName: 'Atlas Cars LLC',
+      billingEmail: 'billing@example.test',
+      invoiceTerms: 'NET_30',
+      netTermsDays: 30,
+    })).toMatchObject({ netTermsDays: 30 })
+
+    expect(() => billingAccountUpdateSchema.parse({ billingEmail: 'not-email', netTermsDays: 366 })).toThrow()
+  })
+
+  it('requires positive money movements for payments, credit notes, and refunds', () => {
+    expect(payBillingInvoiceSchema.parse({ amount: 5000, paymentMethodId: null })).toEqual({ amount: 5000, paymentMethodId: null })
+    expect(() => payBillingInvoiceSchema.parse({ amount: 0 })).toThrow()
+    expect(() => billingCreditNoteSchema.parse({ amount: -1, reason: 'Bad credit' })).toThrow()
+    expect(() => billingRefundSchema.parse({ amount: 0, reason: 'Bad refund' })).toThrow()
+  })
+})
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import {
+  menuItemSchema,
+  menuPlanAssignmentsSchema,
+  menuCompanyAssignmentsSchema,
+  menuPreviewSchema,
+  promotionCreateSchema,
+  promotionUpdateSchema,
+} from './admin.schemas'
+
+describe('admin menu and promotion schemas', () => {
+  it('trims labels and applies safe menu item defaults', () => {
+    expect(menuItemSchema.parse({ label: ' Fleet ', itemType: 'INTERNAL_PAGE' })).toMatchObject({
+      label: 'Fleet',
+      itemType: 'INTERNAL_PAGE',
+      displayOrder: 0,
+      openInNewTab: false,
+      isRequired: false,
+      isActive: true,
+      roles: [],
+      subscriptionPlans: [],
+      companyAssignments: [],
+    })
+  })
+
+  it('rejects negative menu ordering and invalid role previews', () => {
+    expect(() => menuItemSchema.parse({ label: 'Fleet', itemType: 'INTERNAL_PAGE', displayOrder: -1 })).toThrow()
+    expect(() => menuPreviewSchema.parse({ companyId: 'company_1', role: 'SUPER_ADMIN' })).toThrow()
+  })
+
+  it('requires at least one plan or company assignment', () => {
+    expect(() => menuPlanAssignmentsSchema.parse({ assignments: [] })).toThrow()
+    expect(() => menuCompanyAssignmentsSchema.parse({ assignments: [] })).toThrow()
+    expect(menuPlanAssignmentsSchema.parse({ assignments: [{ plan: 'PRO' }] })).toEqual({ assignments: [{ plan: 'PRO' }] })
+  })
+
+  it('accepts only uppercase promotion codes and preserves update partiality', () => {
+    const valid = {
+      code: 'SUMMER_26',
+      name: 'Summer 2026',
+      discountType: 'PERCENTAGE',
+      discountValue: 20,
+      plans: ['STARTER', 'GROWTH'],
+      periods: ['MONTHLY'],
+      validFrom: '2026-07-01T00:00:00.000Z',
+    }
+
+    expect(promotionCreateSchema.parse(valid)).toMatchObject({ ...valid, isActive: true })
+    expect(() => promotionCreateSchema.parse({ ...valid, code: 'summer' })).toThrow()
+    expect(promotionUpdateSchema.parse({ name: 'Updated name' })).toEqual({ name: 'Updated name' })
+  })
+})
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { presentAdminSession, presentAdminUser, presentPaginated } from './admin.presenter'
+
+describe('admin.presenter', () => {
+  it('removes admin secrets from user responses', () => {
+    const result = presentAdminUser({
+      id: 'admin_1',
+      email: 'admin@example.com',
+      role: 'SUPER_ADMIN',
+      passwordHash: 'hash',
+      totpSecret: 'secret',
+    })
+
+    expect(result).toEqual({ id: 'admin_1', email: 'admin@example.com', role: 'SUPER_ADMIN' })
+  })
+
+  it('wraps sessions without leaking credentials', () => {
+    expect(presentAdminSession({ id: 'admin_1', passwordHash: 'hash', totpSecret: 'secret' }, 'jwt-token')).toEqual({
+      token: 'jwt-token',
+      admin: { id: 'admin_1' },
+    })
+  })
+
+  it('computes pagination metadata and preserves extra aggregate fields', () => {
+    expect(presentPaginated([{ id: 'row_1' }], 41, 2, 20, { active: 11 })).toEqual({
+      data: [{ id: 'row_1' }],
+      total: 41,
+      page: 2,
+      pageSize: 20,
+      totalPages: 3,
+      active: 11,
+    })
+  })
+})
@@ -0,0 +1,28 @@
+export function presentAdminUser<T extends Record<string, any>>(admin: T) {
+  const { passwordHash, totpSecret, ...safe } = admin
+  return safe
+}
+
+export function presentAdminSession<T extends Record<string, any>>(admin: T, token: string) {
+  return {
+    token,
+    admin: presentAdminUser(admin),
+  }
+}
+
+export function presentPaginated<T>(
+  data: T[],
+  total: number,
+  page: number,
+  pageSize: number,
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    data,
+    total,
+    page,
+    pageSize,
+    totalPages: Math.ceil(total / pageSize),
+    ...extra,
+  }
+}
@@ -0,0 +1,72 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('../../lib/prisma', () => ({
+  prisma: {
+    adminUser: { findFirst: vi.fn(), findUniqueOrThrow: vi.fn(), update: vi.fn() },
+    auditLog: { create: vi.fn() },
+    company: { findMany: vi.fn(), count: vi.fn(), findUniqueOrThrow: vi.fn(), update: vi.fn(), delete: vi.fn() },
+    billingAccount: { findMany: vi.fn(), count: vi.fn() },
+    $transaction: vi.fn(),
+  },
+}))
+
+import { prisma } from '../../lib/prisma'
+import * as repo from './admin.repo'
+
+describe('admin.repo edge queries', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('clears reset token metadata when updating an admin password', async () => {
+    await repo.updateAdminPassword('admin_1', 'hash_1')
+
+    expect(prisma.adminUser.update).toHaveBeenCalledWith({
+      where: { id: 'admin_1' },
+      data: {
+        passwordHash: 'hash_1',
+        passwordResetToken: null,
+        passwordResetExpiresAt: null,
+      },
+    })
+  })
+
+  it('filters company list by search, status and plan with pagination', async () => {
+    vi.mocked(prisma.company.findMany).mockResolvedValue([] as never)
+    vi.mocked(prisma.company.count).mockResolvedValue(0 as never)
+
+    await repo.listCompaniesPage({ q: 'atlas', status: 'ACTIVE', plan: 'PRO', page: 3, pageSize: 25 })
+
+    const where = {
+      status: 'ACTIVE',
+      OR: [
+        { name: { contains: 'atlas', mode: 'insensitive' } },
+        { email: { contains: 'atlas', mode: 'insensitive' } },
+        { slug: { contains: 'atlas', mode: 'insensitive' } },
+      ],
+      subscription: { plan: 'PRO' },
+    }
+
+    expect(prisma.company.findMany).toHaveBeenCalledWith(expect.objectContaining({
+      where,
+      skip: 50,
+      take: 25,
+      orderBy: { createdAt: 'desc' },
+    }))
+    expect(prisma.company.count).toHaveBeenCalledWith({ where })
+  })
+
+  it('looks up reset tokens only when they have not expired', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-06-01T00:00:00.000Z'))
+
+    await repo.findAdminByResetToken('reset-token')
+
+    expect(prisma.adminUser.findFirst).toHaveBeenCalledWith({
+      where: {
+        passwordResetToken: 'reset-token',
+        passwordResetExpiresAt: { gt: new Date('2026-06-01T00:00:00.000Z') },
+      },
+    })
+
+    vi.useRealTimers()
+  })
+})
--- a/Show More
+++ b/Show More