Skip to content
WasteWise-ProjectPublic

About

A proactive Smart Waste Management System that uses machine learning to predict bin fill levels and CVRP algorithms to optimize municipal collection routes, reducing fleet travel distance.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

WasteWise

WasteWise is a smart waste-collection platform with three services that work together:

  • Frontend — a web dashboard for admins and drivers (React + Vite)
  • Backend — the API server that handles login, bins, vehicles, and routes (NestJS)
  • Algorithm — the AI/ML engine that optimizes collection routes (FastAPI + Python)

You need to run all three at the same time for the app to work.


Table of contents

  1. What you need to install first
  2. Set up the Algorithm service
  3. Set up the Backend service
  4. Set up the Frontend
  5. Seed the database and train the ML model
  6. Run everything and test it
  7. How to use the app (demo walkthrough)
  8. Troubleshooting

1. What you need to install first

Before you do anything else, install the tools below on your computer. Each one has a link to the official download page.

Node.js (version 18 or newer)

Node.js runs the backend and frontend servers.

  • Download: https://nodejs.org — click the LTS button (the left one, not "Current")
  • After installing, open a terminal and run:
    node --version
    npm --version
    
    Both should print version numbers.

Python (version 3.10 or newer)

Python runs the algorithm service.

Windows users: During installation, check the box that says "Add Python to PATH" before clicking Install. Without this, the commands below will not work.

Windows users: On Windows, the command may be python instead of python3. If python3 does not work, try python.


2. Set up the Algorithm service

The algorithm service is a Python application. You need to create a "virtual environment" for it — this is a self-contained Python setup that keeps its packages separate from the rest of your computer.

Open a new terminal window and run these commands one by one:

cd WasteWise/ml

Create a virtual environment:

python3 -m venv .venv

Activate the virtual environment:

  • Mac / Linux:
    source .venv/bin/activate
  • Windows (Command Prompt):
    .venv\Scripts\activate.bat
  • Windows (PowerShell):
    .venv\Scripts\Activate.ps1

After activation, your terminal prompt should show (.venv) at the start — this means it is working.

Install the required Python packages:

pip install -r requirements.txt

This may take a minute or two. When it finishes, start the algorithm server:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

You should see output ending with:

INFO:     Application startup complete.

Leave this terminal window open. The algorithm service must stay running.

You can verify it is working by opening http://localhost:8000/docs in your browser — you should see an API documentation page.


3. Set up the Backend service

Open a second new terminal window and run:

cd WasteWise/api
npm install

npm install downloads all the required packages. It may take a minute.

Then run the database migration to create all the tables in your Neon database:

npm run db:migrate

You should see output confirming the migration ran successfully.

Now start the backend:

npm run start:dev

You should see output ending with something like:

[NestApplication] Nest application successfully started

Leave this terminal window open.

The backend runs at http://localhost:3000


4. Set up the Frontend

Open a third new terminal window and run:

cd WasteWise/web
npm install
npm run dev

You should see:

  VITE v6.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/

Leave this terminal window open.

Open http://localhost:5173 in your browser — you should see the WasteWise login screen.


5. Seed the database and train the ML model

Before you can use the app, you need to:

  1. Add sample bins and a driver account to the database
  2. Generate historical data so the ML model can be trained

Go back to a terminal in the project root (the WasteWise folder, not any subfolder) and run:

cd WasteWise
python3 seed_data.py

This creates 50 bins and the initial accounts in the database.

Then generate historical sensor data for the ML model:

python3 seed_ml_data.py

This generates 90 days of synthetic data and trains the Random Forest model. It may take a minute.

Important: If Python cannot connect to the database, make sure you are connected to the internet — the database is cloud-hosted.


6. Run everything and test it

You should now have three terminal windows open:

Terminal What is running Port
Terminal 1 Algorithm service (Python) 8000
Terminal 2 Backend service (Node.js) 3000
Terminal 3 Frontend (React) 5173

Open http://localhost:5173 in your browser.

Default login accounts

After seeding, the following accounts are available:

Role User Code Password
Admin ADMIN001 admin123
Driver DRV001 driver123

If the seed script created different codes, check the output of seed_data.py — it prints the accounts it created.


7. How to use the app (demo walkthrough)

This is the recommended order to demo WasteWise from scratch.

Log in as Admin using ADMIN001 / admin123.

Step 1 — Fill the bins (simulate time passing)

Go to the Simulation tab. Click Simulate Time (+1 Day) three or four times. Each click randomly adds 5–25% waste to all bins, simulating days passing.

Step 2 — View the map

Go to the Surveillance tab. You will see bins on the map colored by fill level:

  • Green = normal
  • Amber = critical (≥ 75% full)
  • Red = damaged

Step 3 — Generate a reactive route

Go to the Routes tab. Select a vehicle from the dropdown and click Generate Reactive Route. The algorithm collects all currently critical bins and creates the shortest route.

Step 4 — Generate a predictive ML route

Still in the Routes tab, click Generate ML Predictive Route (+24h). A terminal animation plays while the system predicts which bins will overflow in the next 24 hours and creates a proactive route for them.

Step 5 — Switch to Driver view

Log out and log back in as DRV001 / driver123. The driver sees the assigned route, can mark each stop as done one by one, and view progress on the map.

Step 6 — Reset for the next demo

Log back in as Admin, go to Simulation, and click Safe Reset (Set Bins to 0%). This empties all bins without changing their IDs, so the ML model stays valid.


8. Troubleshooting

The frontend shows a network error / cannot connect to API

  • Make sure the backend is running (Terminal 2 shows no errors).
  • Make sure all three terminals are open and none of them show a crash or error.

npm install fails with a permission error on Mac/Linux

npm run db:migrate fails

  • Make sure you are connected to the internet — the database is hosted in the cloud.
  • If it keeps failing, contact the project team to check if the database is active.

Python ModuleNotFoundError

  • Make sure you activated the virtual environment (you should see (.venv) in your terminal).
  • Re-run pip install -r requirements.txt inside the ml folder.

source .venv/bin/activate is not recognized (Windows)

  • Use .venv\Scripts\activate.bat in Command Prompt, or .venv\Scripts\Activate.ps1 in PowerShell.
  • If PowerShell blocks the script, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once and try again.

Login fails even with the correct credentials

  • Make sure the seed script ran successfully (python3 seed_data.py from the project root).
  • Confirm the backend and database are both running with no errors.

Algorithm route generation fails

  • Confirm the algorithm service is running (http://localhost:8000/docs should open in your browser).
  • Make sure Terminal 1 (the Python one) is still open and shows no errors.

Project structure

WasteWise/
├── web/     # React web dashboard
├── api/      # NestJS API server
├── ml/    # FastAPI AI/ML route optimizer
├── seed_data.py            # Creates initial bins and accounts
├── seed_ml_data.py         # Generates ML training data
└── PROJECT_ARCHITECTURE.md # Full system design documentation

For deeper technical details see PROJECT_ARCHITECTURE.md and the README.md inside each service folder.

About

A proactive Smart Waste Management System that uses machine learning to predict bin fill levels and CVRP algorithms to optimize municipal collection routes, reducing fleet travel distance.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages