carmanagement/docs/create-account-guide.md

# Create Account Guide

How to create a new company workspace on RentalDriveGo.

---

## Overview

Creating an account registers a new rental company on the platform. The flow has **4 steps** presented as a multi-step form on the dashboard's public sign-up page. After completion, the company owner receives a confirmation email and can sign in to manage their workspace.

**Supported languages:** English, French, Arabic  
**Billing currency:** MAD (Moroccan Dirham)

---

## 1. Accessing the Sign-up Page

### From the carplace homepage (port 3000)

- Click **"Create Agency Space"** in the header navigation.
- Click **"Get Started"** on any pricing plan card (`/pricing` page).

Both actions navigate to:

```
http://localhost:3000/dashboard/sign-up
```

The carplace proxies this request to the dashboard app (port 3001), which renders the multi-step form.

### URL parameters (optional)

| Parameter | Example | Purpose |
|---|---|---|
| `plan` | `STARTER`, `GROWTH`, `PRO` | Pre-selects a pricing plan |
| `billing` | `MONTHLY`, `ANNUAL` | Pre-selects billing period |
| `currency` | `MAD` | Pre-selects currency (only MAD) |

Example: `/dashboard/sign-up?plan=GROWTH&billing=ANNUAL&currency=MAD`

---

## 2. Form Steps

### Step 1 — Account User

Required fields marked with `*`:

| Field | Type | Details |
|---|---|---|
| Manager/Owner first name * | Bilingual (FR + AR) | Max 80 characters |
| Manager/Owner last name * | Bilingual (FR + AR) | Max 80 characters |
| Manager/Owner email * | Email | Used as login identifier |
| Password * | Password | Minimum 8 characters |
| Confirm password * | Password | Must match |
| Preferred language * | Selection | English / Français / العربية |

**Note:** The same email can be reused for the owner account, company contact, and responsible person.

### Step 2 — Company Info

#### Legal Identity section

| Field | Type | Details |
|---|---|---|
| Commercial name * | Bilingual (FR + AR) | The public-facing business name |
| Legal company name * | Text | Max 160 characters |
| Legal form * | Select | `SARL`, `SARL AU`, `SA`, `SAS`, `AUTO_ENTREPRENEUR`, `EI`, `OTHER` |
| Commercial Registry (RC) * | Text | Max 120 characters |
| ICE number * | Text | Max 120 characters |
| Fiscal ID (IF) * | Text | Max 120 characters |
| Operating license number * | Text | Max 120 characters |
| License issue date * | Date | Format: YYYY-MM-DD |
| Issuing authority * | Text | Max 160 characters |

#### Company Contact section

| Field | Type | Details |
|---|---|---|
| Phone * | Text | Max 80 characters |
| Company contact email * | Email | Max 254 characters |
| Fax | Text | Optional |
| Years active * | Select | `Less than 1 year`, `1 to 5 years`, `More than 5 years` |
| Street Address * | Bilingual (FR + AR) | Max 200 characters |
| City * | Bilingual (FR + AR) | Max 120 characters |
| Country * | Bilingual (FR + AR) | Max 120 characters |
| Zip code * | Text | Max 40 characters |

#### Legal Representative section

| Field | Type | Details |
|---|---|---|
| Legal representative name | Text | Optional, max 160 characters |
| Legal representative title | Text | Optional, max 120 characters |

#### Responsible Person section

| Field | Type | Details |
|---|---|---|
| Responsible person name * | Text | Max 160 characters |
| Responsible person role * | Text | Max 120 characters |
| Responsible person ID number * | Text | Max 120 characters |
| Qualification / diploma * | Text | Optional, max 200 characters |
| Responsible person phone * | Text | Max 80 characters |
| Responsible person email * | Email | Max 254 characters |

### Step 3 — Choose Plan

Select one of three plans:

| Plan | Description |
|---|---|
| **STARTER** | Core fleet, offers, and bookings |
| **GROWTH** | Featured carplace placement and more room to scale |
| **PRO** | Full white-label and premium controls |

Additional options:

| Field | Options |
|---|---|
| Billing period | Monthly / Annual |
| Primary provider | AmanPay / PayPal |

Currency is fixed to **MAD**.

### Step 4 — Review and Launch

Review all entered information. Click **"Create workspace"** to submit.

After successful submission, the page displays a confirmation with:
- The company name
- The owner email
- A link to **"Enter dashboard"** to start using the workspace

---

## 3. Backend API

### Endpoint

```
POST /api/v1/auth/company/signup
```

### Request body (validated by `companySignupSchema`)

```json
{
  "firstName": "string (max 80)",
  "lastName": "string (max 80)",
  "email": "valid email",
  "password": "string (8-128 chars)",
  "companyName": "string (2-120)",
  "legalName": "string (2-160)",
  "legalForm": "string",
  "registrationNumber": "string",
  "iceNumber": "string",
  "taxId": "string",
  "operatingLicenseNumber": "string",
  "operatingLicenseIssuedAt": "string",
  "operatingLicenseIssuedBy": "string",
  "streetAddress": "string",
  "city": "string",
  "country": "string",
  "zipCode": "string",
  "companyPhone": "string",
  "companyEmail": "valid email",
  "fax": "string (optional)",
  "yearsActive": "string",
  "representativeName": "string (optional)",
  "representativeTitle": "string (optional)",
  "responsibleName": "string",
  "responsibleRole": "string",
  "responsibleIdentityNumber": "string",
  "responsibleQualification": "string (optional)",
  "responsiblePhone": "string",
  "responsibleEmail": "valid email",
  "preferredLanguage": "en | fr | ar",
  "plan": "STARTER | GROWTH | PRO",
  "billingPeriod": "MONTHLY | ANNUAL",
  "currency": "MAD",
  "paymentProvider": "AMANPAY | PAYPAL"
}
```

### Response (201 Created)

```json
{
  "companyId": "uuid",
  "companyName": "string",
  "slug": "string",
  "trialEndsAt": "ISO date or null",
  "nextStep": "onboarding",
  "emailDelivery": {
    "attempted": true,
    "success": true,
    "error": null
  }
}
```

---

## 4. After Sign-up

### Sign in

Navigate to `/sign-in` (redirects to `/dashboard/sign-in`). Enter the owner email and the password set during sign-up.

### Onboarding

After first sign-in, the user is directed to the **onboarding** page (`/onboarding`) where they can:

1. **Step 1 — Company profile**: Set display name, tagline, brand color, and public location.
2. **Step 2 — Payments**: Configure AmanPay merchant ID / PayPal email and carplace listing preference.
3. **Step 3 — Completion**: Redirect to the dashboard home.

### Subscription

New accounts start on a **30-day free trial** with the selected plan. The subscription status is shown in a banner on the dashboard home. Users can manage billing from the `/subscription` page.

---

## 5. Relevant Code Files

### Frontend

| File | Purpose |
|---|---|
| `apps/carplace/src/app/renter/sign-up/page.tsx` | Carplace redirect page to dashboard sign-up |
| `apps/dashboard/src/app/sign-up/[[...sign-up]]/page.tsx` | Main multi-step sign-up form (4 steps, 937 lines) |
| `apps/dashboard/src/components/ui/BilingualInput.tsx` | Bilingual (FR/AR) input component |
| `apps/dashboard/src/components/layout/PublicShell.tsx` | Public layout wrapper for the sign-up page |
| `apps/dashboard/src/app/onboarding/page.tsx` | Post-sign-up onboarding (company profile, payments) |
| `apps/dashboard/src/app/forgot-password/page.tsx` | Password reset flow |
| `apps/dashboard/src/app/reset-password/page.tsx` | Reset password page |
| `apps/dashboard/src/app/onboarding/accept-invite/page.tsx` | Accept team invitation |

### Navigation links to sign-up

| File | Location |
|---|---|
| `apps/carplace/src/components/CarplaceHeader.tsx` | "Create Agency Space" button |
| `apps/carplace/src/components/WorkspaceTabs.tsx` | "Owner sign in" link |
| `apps/carplace/src/app/(public)/pricing/PricingClient.tsx` | "Get Started" pricing CTA |
| `apps/carplace/src/app/(public)/HomeContent.tsx` | Homepage CTA |

### Backend

| File | Purpose |
|---|---|
| `apps/api/src/modules/auth/auth.company.routes.ts` | Express routes (`POST /signup`) |
| `apps/api/src/modules/auth/auth.company.service.ts` | Business logic: creates company, owner, workspace, sends email |
| `apps/api/src/modules/auth/auth.company.schemas.ts` | Zod validation schema for signup request body |
| `apps/api/src/lib/emailTranslations.ts` | Email templates in EN/FR/AR |