Full-Stack Car Price Prediction Application

This project is a comprehensive full-stack application that predicts the market price of used cars. It features a modern web interface built with Next.js, a high-performance backend API powered by FastAPI, and a machine learning model trained with XGBoost.

Live Demo: https://your-frontend-url.vercel.app (<- Replace this with your Vercel URL!)

(<- It is highly recommended to replace the placeholder above with a real screenshot of your application's user interface.)

---

Table of Contents

• Project Overview
• Tech Stack
• Features
• The Machine Learning Model
  • Dataset
  • Preprocessing & Feature Engineering
  • Model Training & Evaluation
• Getting Started
  • Prerequisites
  • Backend Setup
  • Frontend Setup
• API Endpoints
• Future Improvements

---

Project Overview

The goal of this project was to build a complete, end-to-end system for predicting used car prices. A user can input various details about a car—such as make, model, year, and mileage—into a user-friendly form. The application then leverages a trained machine learning model to provide an estimated market value in real-time.

This project demonstrates skills across the entire development stack, from data science and model training to backend API development and modern frontend design. It also includes role-based access control for a user/admin dashboard.

---

Tech Stack

This project is built with a modern, high-performance tech stack:

Frontend

• Framework: Next.js (React)
• Styling: Tailwind CSS (or specify what you used, e.g., Material-UI, CSS Modules)
• Deployment: Vercel

Backend

• Framework: FastAPI (Python)
• Server: Uvicorn
• Data Validation: Pydantic
• Deployment: Render

Machine Learning

• Core Libraries: Scikit-learn, Pandas, NumPy
• Algorithm: XGBoost (Extreme Gradient Boosting)
• Workflow: Jupyter Notebook for exploration, Python scripts for final training.

---

Features

• Real-Time Price Prediction: Instantly get a price estimate by filling out a simple form.
• User and Admin Dashboards: Role-based views to manage data and view history.
• Responsive Design: A clean, mobile-first interface that works on any device.
• Interactive API Documentation: Automatically generated by FastAPI (available at the /docs endpoint).

---

The Machine Learning Model

The heart of this application is the predictive model. The development followed a rigorous, iterative process.

Dataset

The model was trained on a dataset of approximately 10,000 used car listings. Key features included:

• marque, modele, annee, kilometrage
• puissance_fiscale, energie, boite

Preprocessing & Feature Engineering

To prepare the data for the model, a robust scikit-learn pipeline was constructed to perform the following steps:

1. Outlier Removal: Prices in the top and bottom 1% were removed to create a more stable model.
2. Target Encoding: The high-cardinality modele feature was intelligently encoded by replacing each model with its average price from the training data, preventing the curse of dimensionality.
3. One-Hot Encoding: Low-cardinality categorical features (marque, energie, boite) were converted into a numerical format.
4. Scaling: All numerical features were standardized using StandardScaler.

Model Training & Evaluation

Several regression algorithms were tested, with XGBoost providing the best performance. The model was further optimized using RandomizedSearchCV to find the best hyperparameters.

The final champion model achieved the following performance on the unseen test set:

• R-squared (R²): 0.76
• Root Mean Squared Error (RMSE): ~18,885

This indicates that the model can explain 76% of the variance in car prices, making it a strong and reliable predictor.

---

Getting Started

To run this project locally, you will need to set up both the backend and frontend separately.

Prerequisites

• Python 3.8+
• Node.js and npm (or yarn)
• Git

Backend Setup

1. Clone the repository:

   git clone https://github.com/your-username/your-backend-repo.git
   cd your-backend-repo

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Run the training script (optional, as the model is pre-trained):

   python train.py 

5. Start the API server:

   uvicorn main:app --reload

   The API will be available at http://120.0.0.1:8000.

Frontend Setup

1. Clone the repository:

   git clone https://github.com/your-username/your-frontend-repo.git
   cd your-frontend-repo

2. Install dependencies:

   npm install

3. Set up environment variables: Create a .env.local file in the root and add the backend API URL:

   NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
   

4. Start the development server:

   npm run dev

   The application will be available at http://localhost:3000.

---

API Endpoints

The primary API endpoint is:

• POST /predict
  • Description: Takes a JSON object with car details and returns a predicted price.
  • Request Body:

    {
      "marque": "Peugeot",
      "modele": "208",
      "puissance_fiscale": 5,
      "kilometrage": 50000,
      "annee": 2020,
      "energie": "Essence",
      "boite": "Manuelle"
    }

  • Success Response:

    {
      "predicted_price": 55432.89
    }

---

Future Improvements

• Hyperparameter Tuning: Implement a more exhaustive search (e.g., more iterations or GridSearchCV) to potentially boost the model's R² score further.
• Advanced Feature Engineering: Create interaction features (e.g., km_per_year) or use domain knowledge to tier car brands into categories like 'Luxury' or 'Economy'.
• Data Enrichment: Integrate external data, such as a car's original MSRP, to provide more context to the model.
• User Authentication: Implement a full JWT-based authentication system for the dashboard features.