carmanagement/apps/dashboard/README.md

# Dashboard App

This document explains the purpose, structure, runtime behavior, and main feature flows of the dashboard application in `apps/dashboard`.

Source of truth:

- `apps/dashboard/src/app/*`
- `apps/dashboard/src/components/*`
- `apps/dashboard/src/lib/*`
- `apps/dashboard/src/hooks/*`
- `apps/dashboard/src/middleware.ts`
- `apps/dashboard/next.config.js`

## Purpose

The dashboard is the internal company workspace for RentalDriveGo. It is the private B2B interface used by rental-company staff to run day-to-day operations.

The app covers:

- employee sign-in
- onboarding after company creation
- fleet management
- reservations and rental lifecycle operations
- online reservation intake
- customer CRM
- contracts and billing
- subscription management
- reviews, complaints, notifications, and settings

It is distinct from:

- the storefront app, which is public and cross-company
- the company site app, which is public and company-branded
- the admin app, which is platform-internal rather than tenant-scoped

## Tech and Runtime

- framework: Next.js 14 App Router
- ui: React 18 + Tailwind CSS
- charts: Recharts
- realtime notifications: `socket.io-client`
- shared types: `@rentaldrivego/types`
- default dev port: `3001`
- base path: `/dashboard`

Defined in `package.json`:

- `npm run dev --workspace @rentaldrivego/dashboard`
- `npm run build --workspace @rentaldrivego/dashboard`
- `npm run start --workspace @rentaldrivego/dashboard`

## URL and Deployment Model

The app is designed to run under `/dashboard`, not at the domain root.

Key behavior from `next.config.js`:

- `basePath` is `/dashboard`
- browser API calls are proxied through `/dashboard/api/*`
- those calls are rewritten to the API origin configured by `API_INTERNAL_URL` or `API_URL`
- image loading allows Cloudinary plus `/storage/*` assets from the API host
- `DASHBOARD_ASSET_PREFIX` can force absolute JS/CSS asset URLs when the dashboard is served behind another frontend proxy

This lets the dashboard run:

- directly in dev on port `3001`
- behind a reverse proxy
- embedded under a shared storefront/admin hostname while still loading its own chunks correctly

## Top-Level Structure

Main folders:

```text
apps/dashboard/
  src/app/
    (dashboard)/        private employee workspace
    (public)/           public shell pages
    onboarding/         post-signup setup
    sign-in/            employee sign-in
    sign-up/            company signup
    forgot-password/
    reset-password/
  src/components/
    layout/             sidebar, topbar, public shell
    reservations/       inspections, photo flows, condition sheet
    team/               invite/edit modals and permissions matrix
    ui/                 shared view components
  src/hooks/
    useTeam.ts          team management data/actions
  src/lib/
    api.ts              cookie-aware API fetch wrapper
    preferences.ts      language/theme persistence scoped per employee
    dashboardPaths.ts   normalizes basePath-aware routes
    urls.ts             resolves storefront/admin app links
  src/middleware.ts     auth gate and redirect logic
```

## Rendering Strategy

Most dashboard screens are client components.

That is a deliberate fit for the app because the dashboard relies heavily on:

- HttpOnly session-cookie authentication
- cookie and embedded-host redirects
- optimistic UI updates
- direct REST fetches after mount
- websocket notification updates
- large interactive forms and modal-heavy workflows

The root `src/app/layout.tsx` is still server-rendered enough to:

- read the shared language cookie
- set `lang` and `dir`
- inject a theme bootstrapping script before hydration

## Auth and Session Model

The dashboard uses API-issued employee sessions stored in an HttpOnly cookie.

### Login flow

`src/app/sign-in/[[...sign-in]]/SignInPageClient.tsx`:

1. submits credentials to `POST /auth/employee/login`
2. receives an HttpOnly `employee_session` cookie from the API
3. stores only non-sensitive employee profile/preferences client-side
4. redirects to the requested dashboard path

The sign-in page also supports:

- language and theme query params
- embedded usage through `postMessage`
- redirect handoff to the admin app after the API sets the admin HttpOnly session cookie

### Protected-route middleware

`src/middleware.ts` protects the app.

Important behavior:

- public dashboard routes are limited to sign-in and forgot-password flows
- all other `/dashboard/*` routes require the `employee_session` cookie
- unauthenticated users are redirected either to the storefront root or to `/dashboard/sign-in`, depending on host context
- duplicate `/dashboard/dashboard` paths are normalized back to `/dashboard`

This means route protection is enforced before React renders the protected pages.

### Role gating

The dashboard does not depend only on route middleware. It also performs UI-level role gating.

Examples:

- the sidebar filters navigation items by employee role
- subscription access is restricted to `OWNER`
- manager/owner-only actions are hidden or disabled in feature pages

Role rank used in the shell:

- `OWNER`
- `MANAGER`
- `AGENT`

## Shell and Navigation

The private shell is defined by:

- `src/app/(dashboard)/layout.tsx`
- `src/components/layout/Sidebar.tsx`
- `src/components/layout/TopBar.tsx`

### Sidebar

Responsibilities:

- tenant branding fetch from `/companies/me/brand`
- current employee profile fetch from `/auth/employee/me`
- role-based navigation filtering
- language and theme controls
- logout handling
- communication with a parent frame when embedded

Main sections exposed in navigation:

- dashboard home
- fleet
- reservations
- online reservations
- customers
- offers
- team
- reports
- subscription
- billing
- contracts
- reviews
- complaints
- notifications
- settings

### Top bar

Responsibilities:

- current page title resolution based on normalized dashboard path
- unread notification count
- compact inbox dropdown
- websocket subscription to realtime notification events

Notification reads are synchronized through the API and local UI events.

## Shared State: Language and Theme

The dashboard uses `DashboardI18nProvider` in `src/components/I18nProvider.tsx`.

It handles:

- current language: `en`, `fr`, `ar`
- current theme: `light`, `dark`
- full in-app copy dictionaries
- persistence to cookies and `localStorage`
- per-employee scoped preferences using non-sensitive cached profile metadata

`src/lib/preferences.ts` is the key utility here. It stores both:

- shared values like `rentaldrivego-language`
- employee-scoped variants so one staff member does not override another on the same device

Arabic also flips layout direction through the root layout by setting `dir="rtl"`.

## Data Fetching Conventions

The dashboard centralizes API access in `src/lib/api.ts`.

### `apiFetch`

Browser fetch behavior:

- never reads authentication tokens from `localStorage`
- sends authenticated requests with the HttpOnly session cookie
- defaults JSON requests to `Content-Type: application/json`
- preserves `FormData` for file uploads
- includes credentials for cookie-aware flows
- unwraps `{ data }` responses automatically

Browser base URL:

- `NEXT_PUBLIC_API_URL`
- fallback `/dashboard/api/v1`

### `apiFetchServer`

Server-side helper for routes/components that explicitly receive a trusted server-side token and need `cache: 'no-store'`. Browser code should use HttpOnly cookies instead.

### Pattern used across pages

Most pages follow the same client-side pattern:

1. mount
2. call one or more `apiFetch(...)` requests
3. store result in local component state
4. show loading and empty states
5. mutate through API actions
6. refetch or patch local state

There is intentionally very little abstraction beyond this. The code favors explicit page-level orchestration over a large client data framework.

## Feature Areas

### 1. Company signup and onboarding

Relevant routes:

- `src/app/sign-up/[[...sign-up]]/page.tsx`
- `src/app/onboarding/page.tsx`

The signup screen creates the company through:

- `POST /auth/company/signup`

The onboarding flow then completes the initial tenant setup in three steps:

1. basic company info via `PATCH /companies/me`
2. brand/public profile via `PATCH /companies/me/brand`
3. payment and storefront settings via `PATCH /companies/me/brand`

This makes onboarding a dashboard-owned continuation of the API signup flow.

### 2. Dashboard home

Route:

- `src/app/(dashboard)/page.tsx`

Backed by:

- `GET /analytics/dashboard`

Primary contents:

- KPI cards
- source breakdown chart
- subscription-status banner
- recent reservations list

Revenue visibility is reduced for lower-privilege roles.

### 3. Fleet

Routes:

- `src/app/(dashboard)/fleet/page.tsx`
- `src/app/(dashboard)/fleet/[id]/page.tsx`
- `src/components/VehicleCalendar.tsx`

Backed by:

- `GET /vehicles`
- `POST /vehicles`
- `GET /vehicles/:id`
- `PATCH /vehicles/:id`
- `PATCH /vehicles/:id/status`
- `POST /vehicles/:id/photos`
- `DELETE /vehicles/:id/photos/:idx`
- `GET /vehicles/:id/maintenance`
- `POST /vehicles/:id/maintenance`
- `GET /vehicles/:id/calendar`
- `POST /vehicles/:id/calendar/blocks`
- `DELETE /vehicles/:id/calendar/blocks/:blockId`

Key responsibilities:

- create and edit vehicles
- upload vehicle images
- publish/unpublish vehicles
- change operational status
- record maintenance
- visualize reservations and manual blocks on a calendar
- configure pickup and dropoff location rules

### 4. Reservations

Routes:

- `src/app/(dashboard)/reservations/page.tsx`
- `src/app/(dashboard)/reservations/new/page.tsx`
- `src/app/(dashboard)/reservations/[id]/page.tsx`

Backed by:

- `GET /reservations`
- `POST /reservations`
- `GET /reservations/:id`
- `PATCH /reservations/:id`
- `POST /reservations/:id/confirm`
- `POST /reservations/:id/checkin`
- `POST /reservations/:id/checkout`
- `POST /reservations/:id/close`
- `POST /reservations/:id/extend`
- `PUT /reservations/:id/inspections/:type`
- `PATCH /reservations/:id/additional-drivers/:driverId/approval`
- `GET|POST|DELETE /reservations/:id/photos*`

This is the heaviest operational area of the dashboard.

Major workflows:

- create draft bookings
- choose existing or new customers
- upload and manage customer license images
- confirm/check-in/check-out/close rentals
- edit booking vs return data based on reservation workflow state
- complete check-in/check-out inspections
- upload pickup and dropoff photos
- extend rentals
- approve additional drivers

Supporting reservation UI components:

- `DamageInspectionCard.tsx`
- `ReservationPhotoSection.tsx`
- `VehicleConditionSheet.tsx`

### 5. Online reservations

Route:

- `src/app/(dashboard)/online-reservations/page.tsx`

Backed by:

- `GET /reservations?source=MARKETPLACE&status=DRAFT`
- `POST /reservations/:id/confirm`
- `POST /reservations/:id/cancel`

This page is the triage surface for new public booking requests before staff converts them into active operational reservations.

### 6. Customers

Route:

- `src/app/(dashboard)/customers/page.tsx`

Backed mainly by:

- `GET /customers`

The reservations-create flow also uses:

- `POST /customers`
- `PATCH /customers/:id`
- `POST /customers/:id/license-image`

The customer surface acts as a company-local CRM rather than a global renter account manager.

### 7. Offers

Route:

- `src/app/(dashboard)/offers/page.tsx`

Backed by:

- `GET /offers`
- `GET /offers/:id`
- `POST /offers`
- `PATCH /offers/:id`
- `DELETE /offers/:id`
- `GET /vehicles`

Purpose:

- create and edit discounts
- target specific vehicles
- manage promo details and active/public state

### 8. Team

Route:

- `src/app/(dashboard)/team/page.tsx`

Supporting hook and components:

- `src/hooks/useTeam.ts`
- `components/team/InviteModal.tsx`
- `components/team/EditMemberModal.tsx`
- `components/team/PermissionsMatrix.tsx`

Backed by:

- `GET /team`
- `GET /team/stats`
- `POST /team/invite`
- `PATCH /team/:id/role`
- `POST /team/:id/deactivate`
- `POST /team/:id/reactivate`
- `DELETE /team/:id`

This area centralizes employee lifecycle management.

### 9. Reports

Route:

- `src/app/(dashboard)/reports/page.tsx`

Backed by:

- `GET /analytics/report?period=...`

Purpose:

- revenue and operational analytics
- summarized reporting views

### 10. Subscription

Route:

- `src/app/(dashboard)/subscription/page.tsx`

Backed by:

- `GET /subscriptions/me`
- `GET /subscriptions/invoices`
- `GET /subscriptions/providers`
- `GET /subscriptions/plans`
- `GET /subscriptions/features`
- `POST /subscriptions/checkout`
- `POST /subscriptions/cancel`
- `POST /subscriptions/resume`

This is owner-only and manages the SaaS relationship between the company and RentalDriveGo.

Key functions:

- current plan visibility
- plan comparison
- provider availability checks
- checkout redirection
- invoice history
- cancel/resume lifecycle

### 11. Billing

Route:

- `src/app/(dashboard)/billing/page.tsx`

Backed by:

- `GET /reservations`
- `GET /payments/company`
- `POST /payments/reservations/:id/manual`

This page handles customer-side rental billing, not SaaS subscription billing.

It focuses on:

- reservation invoice state
- collected vs outstanding balances
- payment history
- manual payment recording
- quick jumps to reservation and contract pages

### 12. Contracts

Routes:

- `src/app/(dashboard)/contracts/page.tsx`
- `src/app/(dashboard)/contracts/[id]/page.tsx`

Backed by:

- `GET /reservations`
- `GET /reservations/:id/contract`

Purpose:

- list reservations with contract/invoice state
- generate and reopen rental-contract views
- present printable contract payloads for staff operations

### 13. Reviews and complaints

Routes:

- `src/app/(dashboard)/reviews/page.tsx`
- `src/app/(dashboard)/complaints/page.tsx`

Backed by:

- `GET /reviews`
- `GET /reviews/stats`
- `PATCH /reviews/:id/reply`
- `GET /complaints`
- `POST /complaints`
- `PATCH /complaints/:id`

These pages give staff post-rental quality and dispute management tools.

### 14. Notifications

Route:

- `src/app/(dashboard)/notifications/page.tsx`

Backed by:

- `GET /notifications/company`
- `GET /notifications/history`
- `GET /notifications/company/preferences`
- `POST /notifications/company/:id/read`
- `POST /notifications/company/read-all`
- `PATCH /notifications/company/preferences`

This page complements the top-bar notification dropdown by adding:

- full inbox view
- delivery history audit
- per-event, per-channel preference management

### 15. Settings

Route:

- `src/app/(dashboard)/settings/page.tsx`

Backed by:

- `GET|PATCH /companies/me/brand`
- `POST /companies/me/brand/logo`
- `POST /companies/me/brand/hero`
- `POST|DELETE /companies/me/brand/custom-domain`
- `GET|PATCH /companies/me/contract-settings`
- `GET|POST|PATCH /companies/me/insurance-policies`
- `GET|POST|PATCH /companies/me/pricing-rules`
- `GET|PATCH /companies/me/accounting-settings`

This is the broad configuration surface for the tenant.

It includes:

- public brand and storefront profile
- payment account identifiers
- custom domain setup
- rental policies
- insurance products
- pricing rules
- accounting defaults

## Public Shell Pages

Public-facing dashboard pages live outside the private shell.

Notable routes:

- `/dashboard/sign-in`
- `/dashboard/sign-up`
- `/dashboard/forgot-password`
- `/dashboard/reset-password`
- `/dashboard/onboarding`

Layout:

- `src/app/(public)/layout.tsx`
- `src/components/layout/PublicShell.tsx`
- `src/components/layout/PublicHeader.tsx`
- `src/components/layout/PublicFooter.tsx`

These pages share the branding system and language/theme controls but do not render the private sidebar/topbar shell.

## Embedded and Cross-App Behavior

The dashboard supports embedded scenarios.

Examples in the code:

- sign-in posts messages to the parent frame
- logout posts an employee-logout event
- current embedded path is reported upward

It also coordinates with sibling apps:

- `storefrontUrl` links staff back to the public storefront domain
- `adminUrl` supports cookie-based handoff into the admin interface
- host-aware URL rewriting allows the same app to function under external domains, internal Docker hostnames, and proxied environments

## API Dependency Summary

The dashboard is a thin client over the company API. Its main backend dependencies are:

- auth: employee login and profile
- companies: brand, contract settings, pricing rules, accounting, domains
- vehicles: fleet CRUD, photos, maintenance, availability calendar
- reservations: booking lifecycle and inspections
- customers: CRM and license documents
- offers: promotions
- team: employee management
- analytics: dashboard and reports
- notifications: inbox, history, preferences
- subscriptions: SaaS plan management
- payments: rental payment recording
- reviews and complaints: post-rental follow-up

The frontend does not try to reproduce business rules locally. It delegates workflow authority to the API and reflects the resulting state.

## Design Characteristics

The current dashboard code favors:

- explicit page-local state over a global data layer
- direct REST integration over generated clients
- strong tenant scoping through backend auth rather than frontend assumptions
- rich operational forms over minimal CRUD scaffolds
- multilingual support directly in the app shell

Tradeoffs of this approach:

- easy to reason about per page
- low indirection when debugging API interactions
- more repeated fetch/state patterns than a centralized query layer would have
- large single-file page components in the heaviest screens

## Recommended Maintenance Rules

When changing the dashboard, keep these rules in mind:

1. Preserve the `/dashboard` base path and `toDashboardAppPath` normalization behavior.
2. Keep route protection aligned with `src/middleware.ts`.
3. If a new page depends on employee role, gate it both in navigation and in-page behavior.
4. Reuse `apiFetch` for auth and error handling consistency.
5. Keep language/theme strings inside the dashboard i18n system rather than scattering literals.
6. Update this README when a new major page, workflow, or integration pattern is added.