Installation Guide

Before You Start

Get these sorted first. Takes five minutes and saves an hour of confusion later.

• Python 3.10 or newer. Grab it from python.org. On Windows, tick the "Add Python to PATH" checkbox during install — miss it and every command below fails with "python is not recognized".
• pip comes bundled with Python. Check with pip --version.
• About 2 GB of free disk space. The ML artifacts alone are around 1 GB.
• A code editor. VS Code is fine.

API keys are optional. You do not need them to run this.

Step 1 — Extract the project

Unzip the downloaded folder somewhere sensible. Not Downloads. Something like C:\projects\intelliflow or ~/projects/intelliflow. Open a terminal and cd into that folder. You should see manage.py when you type dir on Windows or ls on Mac and Linux.

Step 2 — Put the ML artifacts in place

This is the step people skip, so read it twice.

Your purchase email has a separate link for artifacts.zip. Download it and extract it inside the ml/ folder. When you're done, the path ml/artifacts/models/ must exist and contain files like BEST_classifier.pkl and BEST_regressor.pkl.

The final structure looks like this:

intelliflow/
└── ml/
    ├── features.py
    └── artifacts/
        ├── models/
        ├── encoders/
        ├── metadata/
        └── figures/

Do not rename features.py and do not edit it. Training used that exact file. Change it and your predictions become meaningless.

Step 3 — Create a virtual environment

python -m venv venv

Then activate it.

Windows:

venv\Scripts\activate

Mac or Linux:

source venv/bin/activate

You'll see (venv) appear at the start of your terminal line. That means it worked. Keep this activated for every command from here on.

Step 4 — Install dependencies

pip install -r requirements.txt

This pulls Django 5.2, LightGBM, scikit-learn, pandas, Channels, Daphne and a few others. Takes three to eight minutes depending on your connection. LightGBM is usually the slow one.

If you want the vehicle detection module, add this too:

pip install ultralytics

Step 5 — Set up your environment file

Copy the template:

copy .env.example .env

On Mac or Linux use cp .env.example .env instead.

Open .env in your editor. You can leave TOMTOM_API_KEY and ORS_API_KEY empty. The app will run in simulated mode. If you want the route planner working, register at openrouteservice.org for a free key and paste it in.

Step 6 — Build the database and load data

Run these four commands one after another. Wait for each to finish.

python manage.py migrate
python manage.py seed_from_artifacts
python manage.py create_superuser_fixture
python manage.py run_predictions

What each one does: migrate creates the SQLite tables. seed_from_artifacts loads the 16 intersections and 35 days of historical traffic data. create_superuser_fixture makes your login accounts. run_predictions loads the models and generates tomorrow's forecast for every intersection — this one takes the longest, maybe 30 seconds, because it's loading model files from disk.

The seed command is safe to run twice. It won't duplicate anything.

Step 7 — Start it

python manage.py runserver

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

Log in with:

• admin / admin123 for full access including Django admin
• operator / operator123 for dashboard-only access

Change these before you show anything to anyone outside your college.

How to Check Everything Actually Works

There's a built-in command for this:

python manage.py check_deploy

It verifies the artifact folders exist, the key model files are present, the registry loads, the feature contract still has 83 columns, and the database has seeded data. All green means you're good.

Manual check, faster: open /dashboard/ and confirm the summary cards show numbers instead of zeros. Then open /map/ — you should see 16 coloured circles over Bengaluru. Click one, a popup with prediction data appears. If both of those work, everything downstream works.

When Things Go Wrong

"Model registry failed to load" or an error mentioning artifacts

Ninety percent of the time this is Step 2. Check that ml/artifacts/models/ exists and isn't empty. A common mistake is extracting the zip and ending up with ml/artifacts/artifacts/models/ — one folder too deep. Move it up a level.

InsufficientHistoryError when running predictions

The models need at least 21 days of history per intersection to compute lag and rolling features. If you flushed the database or ran run_predictions before seed_from_artifacts, you'll hit this. Run the seed command, then predictions again, in that order.

The map loads but never updates in real time

Check you're running a single process. If you started this with Gunicorn or added --workers 4 anywhere, the in-memory channel layer breaks because each worker has its own separate copy. Use runserver or a single Daphne instance. The map still refreshes every 60 seconds through polling, so the page won't look broken — just stale.

Vision upload spins forever the first time

It's downloading yolov8n.pt, roughly 6 MB. Wait it out once, or pre-download it before your demo:

python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"

"No module named django" after reopening your terminal

Your virtual environment isn't active. Run the activate command from Step 3 again. This happens every single time you close and reopen the terminal, and it catches everyone at least once.

Running the Tests

Nice thing to show your guide:

python -m pytest tests/ -v

Eight tests covering role permissions, feature contract integrity, registry loading, seed idempotency and route penalty logic. All eight should pass.