## 1. System Overview

The Vehicle Listing System allows verified dealers to manage their profiles and add vehicle listings. All listings go through an admin approval process before being visible to the public.

### System Architecture

Dealer Registration
→
Admin Approval
→
Verified Dealer
→
Add Listings
→
Admin Review
→
Public Platform

## 2. Dealer Profile Management

Dealers can manage their profile information including company details, location, and contact information.

#### 📌 Important: Separate Dealer Layout & Routes

Dealer routes are completely separate from admin routes:

- All dealer routes use the `/dealers/*` prefix
- Dealer profile routes: `/dealers/profile/*` (NOT `/admin/profile/*`)
- Dealers have their own layout: `layouts.dealer.app`
- Dealers have their own header and navigation menu
- Profile navigation shows dealer-specific sections

### Step-by-Step Guide

1. Login to Dealer Dashboard
   Navigate to: GET/dealers/login
   - Only verified dealers (status = ACTIVE) can access the dashboard
   - Dealers with PENDING status will see approval message
2. Access Profile
   Go to: GET/dealers/profile
   - View current dealer information
   - Navigate to different profile sections (Account, Company, Representative, Financial, Business, Documents)
   - Separate dealer layout and navigation
3. Update Account Information
   Routes:
   - POST/dealers/profile - Edit form
   - PUT/dealers/profile - Update account data

   Fields: First Name, Last Name, Phone, Gender, Date of Birth

4. Update Company Information
   Routes:
   - POST/dealers/profile/company - Edit form
   - PUT/dealers/profile/company - Update data

   Fields: Company Name, Registration Number, Tax ID, Address (Country, State, City, Street, Postal Code)

5. Manage Authorized Representative Information
   Routes:
   - POST/dealers/profile/representative/create - Show add form
   - POST/dealers/profile/representative - Store new representative
   - POST/dealers/profile/representative/{id} - Edit form
   - PUT/dealers/profile/representative/{id} - Update data

   Fields: Full Name*, NIC/Passport, Position, Contact Phone, Contact Email

   Layout: Table view with add/edit functionality

6. Manage Bank & Financial Information
   Routes:
   - POST/dealers/profile/financial/create - Show add form
   - POST/dealers/profile/financial - Store new financial info
   - POST/dealers/profile/financial/{id} - Edit form
   - PUT/dealers/profile/financial/{id} - Update data

   Fields: Bank Name*, Account Holder Name*, Account Number*

   Layout: Table view with add/edit functionality

7. Update Business Information
   Routes:
   - POST/dealers/profile/business - Edit form
   - PUT/dealers/profile/business - Update data

   Fields: Operations, Branches, Website

8. Manage Documents
   Routes:
   - POST/dealers/profile/documents - Edit form
   - PUT/dealers/profile/documents - Update/Upload documents
9. Update Avatar
   Routes:
   - POST/dealers/profile/avatar - Edit form
   - PUT/dealers/profile/avatar - Update avatar
10. Change Password
    Routes:
    - POST/dealers/profile/password - Edit form
    - PUT/dealers/profile/password - Update password
11. View Terms
    Route: GET/dealers/profile/terms
12. Update Settings
    Route: POST/dealers/settings
    - Dark mode toggle
    - Compact sidebar toggle

## 3. Add Vehicle Listing - Complete Feature

### Step-by-Step Guide

1. Navigate to Listings
   From Dealer Dashboard, go to: GET/dealers/listings
2. Create New Listing
   Click "Add New Listing" → GET/dealers/listings/create
3. Fill Required Fields

   Field | Description | Validation
   --- | --- | ---
   VIN | Vehicle Identification Number | Required, exactly 17 characters, unique
   Make | Manufacturer (e.g., Honda, Toyota) | Required, max 255 characters
   Model | Vehicle model name | Required, max 255 characters
   Year | Manufacturing year | Required, integer (1900 to current year + 1)
   Trim | Edition/variant | Optional, max 255 characters
   Mileage | Vehicle mileage | Required, integer, min 0
   Price | Listing price | Required, numeric, min 0
   Condition | Vehicle condition | Required, select from: New, Used, Certified Pre-Owned
   Exterior Color | Vehicle exterior color | Required, max 255 characters
   Interior Color | Vehicle interior color | Required, max 255 characters
   Car Photos | Multiple vehicle images | Required, minimum 3 images, max 5MB each
   Description | Vehicle description | Optional, text field

4. Upload Images
   Use: POST/dealers/listings/upload-image
   - Drag and drop or click to upload
   - Supported formats: JPEG, JPG, PNG, GIF, WEBP
   - Maximum file size: 5MB per image
   - Minimum 3 images required
5. Submit Listing
   Route: POST/dealers/listings
   - Listing is created with Status: PENDING
   - Admin receives notification for approval
   - Dealer sees confirmation message

### Listing Workflow

Dealer Creates
Listing
→
Status: PENDING
(Awaiting Admin)
→
Admin Reviews
Listing
→
Status: APPROVED
(Visible on Platform)

OR

Dealer Creates
Listing
→
Status: PENDING
→
Admin Rejects
Listing
→
Status: SUSPENDED
(Not Visible)

## 4. Admin Approval Process

### For Listings

1. View Pending Listings
   Admin Dashboard → Listings → GET/admin/listings
2. Review Listing Details
   Click on listing → GET/admin/listings/{uuid}
   - View all vehicle specifications
   - Check images
   - Review dealer information
3. Approve Listing
   Route: POST/admin/listings/{id}/approve
   - Changes status from PENDING → APPROVED
   - Listing becomes visible on public platform
   - Dealer receives notification
4. Reject Listing
   Route: POST/admin/listings/{id}/reject
   - Changes status from PENDING → SUSPENDED
   - Listing is hidden from public platform
   - Dealer receives notification

### For Dealers

1. View Pending Dealers
   Admin Dashboard → Dealers → GET/admin/dealers
2. Verify Email (Optional)
   Route: POST/admin/dealers/verify-email/{uuid}
   - Changes user status to VERIFIED
3. Approve Dealer
   Route: POST/admin/dealers/approve/{uuid}
   - Sets user status to ACTIVE
   - Sets verified_at timestamp
   - Dealer can now login and access dashboard
4. Reject Dealer
   Route: POST/admin/dealers/reject/{uuid}
   - Sets user status to SUSPENDED
   - Dealer cannot access dashboard

## 5. Data Flow & Database Structure

### Complete Data Flow Diagram

#### 1. Dealer Registration

Dealer fills registration form

Tables: dealers, users, dealer_representatives, dealer_finances, addresses

↓

#### 2. Admin Approval

Admin reviews and approves dealer

Status Update: users.status = ACTIVE

↓

#### 3. Dealer Adds Listing

Dealer creates vehicle listing

Tables: listings, vehicle_specifications, listing_features

Status: listings.status = PENDING

↓

#### 4. Admin Reviews Listing

Admin approves or rejects

Status: APPROVED or SUSPENDED

↓

#### 5. Public Platform

Approved listings are visible

Query: WHERE status = APPROVED

### Database Tables Structure

Table | Key Fields | Purpose
--- | --- | ---
users | id, email, status, password | User accounts (dealers, admins, buyers)
dealers | id, company_name, registration_number, tax_identification_number, verified_at | Dealer company information
listings | id, title, price, location, owner_id, status, condition_id, image_url | Vehicle listings
vehicle_specifications | listing_id, make, model, year, vin, mileage, trim, exterior_color, interior_color | Detailed vehicle specifications
conditions | id, name, slug (New, Used, Certified Pre-Owned) | Vehicle condition options
listing_features | listing_id, feature_id | Many-to-many: listings ↔ vehicle_features
dealer_representatives | dealer_id, full_name, nic_number, position, contact_phone | Dealer contact person information
addresses | addressable_id, addressable_type, country, state, city, street, postal_code | Polymorphic: dealer/branch addresses

### Key Relationships

users (1) ──→ (1) dealers │ └──→ (many) listings │ ├──→ (1) vehicle_specifications ├──→ (1) conditions └──→ (many) listing_features

## 6. API Routes Reference

### Dealer Routes (Protected: auth, verified, verified_dealer)

Method | Route | Action
--- | --- | ---
GET | /dealers/login | Dealer login page
POST | /dealers/login | Process dealer login
GET | /dealers/dashboard | Dealer dashboard (separate layout)
GET | /dealers/profile | Dealer profile page (separate layout)
GET | /dealers/listings | List all dealer's listings
GET | /dealers/listings/create | Show create listing form
POST | /dealers/listings | Store new listing
POST | /dealers/listings/upload-image | Upload listing image
GET | /dealers/listings/{id} | Show listing details
GET | /dealers/listings/{id}/edit | Show edit form
PUT | /dealers/listings/{id} | Update listing
DELETE | /dealers/listings/{id} | Delete listing

### Admin Routes (Protected: auth, active)

Method | Route | Action
--- | --- | ---
GET | /admin/listings | List all listings (DataTable)
POST | /admin/listings/{id}/approve | Approve listing
POST | /admin/listings/{id}/reject | Reject listing
GET | /admin/dealers | List all dealers (DataTable)
POST | /admin/dealers/approve/{uuid} | Approve dealer
POST | /admin/dealers/reject/{uuid} | Reject dealer

### Dealer Profile Management Routes (Protected: auth, verified, verified_dealer)

Method | Route | Action
--- | --- | ---
GET | /dealers/profile | View dealer profile index
POST | /dealers/profile | Show edit account form
PUT | /dealers/profile | Update account information
POST | /dealers/profile/company | Show edit company form
PUT | /dealers/profile/company | Update company information
POST | /dealers/profile/representative/create | Show add representative form
POST | /dealers/profile/representative | Store new representative
POST | /dealers/profile/representative/{id} | Show edit representative form
PUT | /dealers/profile/representative/{id} | Update representative
POST | /dealers/profile/financial/create | Show add financial info form
POST | /dealers/profile/financial | Store new financial information
POST | /dealers/profile/financial/{id} | Show edit financial form
PUT | /dealers/profile/financial/{id} | Update financial information
POST | /dealers/profile/business | Show edit business form
PUT | /dealers/profile/business | Update business information
POST | /dealers/profile/documents | Show edit documents form
PUT | /dealers/profile/documents | Update/Upload documents
GET | /dealers/profile/terms | View terms of service
POST | /dealers/profile/avatar | Show edit avatar form
PUT | /dealers/profile/avatar | Update avatar
POST | /dealers/profile/password | Show change password form
PUT | /dealers/profile/password | Update password
POST | /dealers/settings | Update dealer settings (dark mode, sidebar)

## 7. Status Flow & Enums

### User Status Enum

Value | Enum | Description
--- | --- | ---
0 | PENDING | Initial registration status
1 | ACTIVE | Approved and can login
2 | APPROVED | Additional approval level
3 | VERIFIED | Email verified
6 | SUSPENDED | Rejected or suspended

### Listing Status Flow

PENDING
(Created by Dealer)
→
APPROVED
(Visible on Platform)
OR
SUSPENDED
(Rejected by Admin)

## 8. Implementation Timeline

#### Phase 1: Dealer Authentication & Profile Management COMPLETED

Estimated Time: 8-12 hours

- Dealer login system with verification middleware
- Separate dealer layout and navigation system
- Dealer profile management with dedicated routes (/dealers/profile/*)
- Table layouts for Representatives and Financial Information
- Add/Edit functionality for representatives and financial records
- Admin approval/rejection for dealers

#### Phase 2: Vehicle Listing System COMPLETED

Estimated Time: 12-16 hours

- Create listings with all required fields
- Multiple image upload functionality
- Conditions table and relationships
- Listing validation and storage

#### Phase 3: Admin Approval System COMPLETED

Estimated Time: 6-8 hours

- Admin listing review interface
- Approve/reject endpoints
- Status management
- DataTable integration

#### Phase 4: Database & Migrations COMPLETED

Estimated Time: 4-6 hours

- Conditions table creation
- Foreign key relationships
- Seeder for conditions

#### Phase 5: Testing & Documentation IN PROGRESS

Estimated Time: 4-6 hours

- End-to-end testing
- Documentation creation (this guide)
- Visual workflow diagrams

### Total Estimated Time: 34-48 hours

Current Status: Core functionality completed. Remaining work: Testing, edge cases, and UI polish.

## 9. Quick Start Guide

### For Dealers

1. Register: Go to /dealers-register
2. Wait for Approval: Admin will approve your account
3. Login: Use /dealers/login with your credentials
4. Access Dashboard: After login, you'll be redirected to /dealers/dashboard
5. Update Profile: Click on "Profile" in navigation → /dealers/profile
6. Manage Representatives: Add/Edit authorized representatives with table view
7. Manage Financial Info: Add/Edit bank account information with table view
8. Add Listings: Go to Listings → Add New
9. Wait for Approval: Admin reviews and approves listings

### For Admins

1. Review Dealers: Admin Dashboard → Dealers
2. Approve Dealers: Click approve button on pending dealers
3. Review Listings: Admin Dashboard → Listings
4. Approve/Reject: Click approve or reject on pending listings
5. Manage Platform: All approved listings appear on public platform

### System Status: Operational ✅

All core features have been implemented and tested.

For technical support or questions, please contact the development team.