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.
- What you need to install first
- Set up the Algorithm service
- Set up the Backend service
- Set up the Frontend
- Seed the database and train the ML model
- Run everything and test it
- How to use the app (demo walkthrough)
- Troubleshooting
Before you do anything else, install the tools below on your computer. Each one has a link to the official download page.
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:
Both should print version numbers.
node --version npm --version
Python runs the algorithm service.
- Download: https://www.python.org/downloads
- After installing, open a terminal and run:
It should print something like
python3 --versionPython 3.11.x.
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
pythoninstead ofpython3. Ifpython3does not work, trypython.
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/mlCreate a virtual environment:
python3 -m venv .venvActivate 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.txtThis may take a minute or two. When it finishes, start the algorithm server:
uvicorn main:app --host 0.0.0.0 --port 8000 --reloadYou 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.
Open a second new terminal window and run:
cd WasteWise/api
npm installnpm 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:migrateYou should see output confirming the migration ran successfully.
Now start the backend:
npm run start:devYou should see output ending with something like:
[NestApplication] Nest application successfully started
Leave this terminal window open.
The backend runs at http://localhost:3000
Open a third new terminal window and run:
cd WasteWise/web
npm install
npm run devYou 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.
Before you can use the app, you need to:
- Add sample bins and a driver account to the database
- 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.pyThis creates 50 bins and the initial accounts in the database.
Then generate historical sensor data for the ML model:
python3 seed_ml_data.pyThis 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.
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.
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.
This is the recommended order to demo WasteWise from scratch.
Log in as Admin using ADMIN001 / admin123.
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.
Go to the Surveillance tab. You will see bins on the map colored by fill level:
- Green = normal
- Amber = critical (≥ 75% full)
- Red = damaged
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.
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.
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.
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.
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
- Do not use
sudo npm install. Instead, follow the guide at https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally to fix npm permissions.
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.txtinside themlfolder.
source .venv/bin/activate is not recognized (Windows)
- Use
.venv\Scripts\activate.batin Command Prompt, or.venv\Scripts\Activate.ps1in PowerShell. - If PowerShell blocks the script, run
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedonce and try again.
Login fails even with the correct credentials
- Make sure the seed script ran successfully (
python3 seed_data.pyfrom 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.
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.