Installation Guide

Before You Start

Set aside about 30 minutes the first time. Most of that is downloads, not work.

• Python 3.11 — grab it from python.org. Not 2.7, and not 3.13 either, since some dependencies lag behind on the newest release. On Windows, tick "Add Python to PATH" during install or you'll be fighting your terminal for the next hour.
• Flutter SDK 3.x — from flutter.dev. After installing, run flutter doctor and fix whatever it complains about. Android licenses usually need accepting with flutter doctor --android-licenses.
• Android Studio — for the emulator. Or just plug in a real phone with USB debugging on, which honestly runs smoother than most laptops' emulators.
• Git — for cloning.
• Optional: a free Groq API key for the LLM explanations, and a Google Safe Browsing API key. Both are free tiers. The project runs without them, just with fewer signals and template-based explanations.
• Optional: Redis, only if you want real background workers. Skip it for now.

Part 1: The Django Backend

Step 1 — Open the backend folder

Unzip the project, open a terminal, and move into the backend directory.

cd backend

Step 2 — Create a virtual environment

This keeps the project's packages separate from everything else on your machine.

python -m venv .venv

Then activate it. On Windows: .venv\Scripts\activate. On macOS or Linux: source .venv/bin/activate. You'll know it worked because (.venv) appears at the start of your terminal line. If it doesn't appear, the activation failed and everything after this will install to the wrong place.

Step 3 — Install the dependencies

pip install -r requirements.txt

This pulls in Django 5, DRF, Celery, the analyzer libraries, and everything else. Takes two or three minutes on decent internet.

Step 4 — Set up your environment file

Copy the example file: cp .env.example .env (on Windows use copy .env.example .env).

Open .env in any text editor. The only mandatory value is SECRET_KEY — type any long random string of characters, it doesn't need to be anything official. If you have the Groq and Safe Browsing keys, paste them in the matching lines. Leave the rest as-is.

Step 5 — Create the database

python manage.py migrate

This builds the SQLite database along with the risk rule table, the blacklist table, and everything else. No separate database server to install.

Step 6 — Make yourself an admin

python manage.py createsuperuser

Pick a username and password you'll remember. You'll need this to open the moderation queue and edit risk rules at /admin/.

Step 7 — Start it up

python manage.py runserver

Leave this terminal running. Open http://127.0.0.1:8000/admin/ in your browser and log in. If you see the Django admin dashboard with the risk rules listed, the backend is done.

Part 2: The Flutter App

Step 8 — Fetch the packages

Open a second terminal, don't close the backend one.

cd mobile
flutter pub get

Step 9 — Point the app at your backend

Open lib/core/network/dio_client.dart. You'll find a base URL set to http://10.0.2.2:8000/api/v1/.

• Android emulator: leave it alone, it already works.
• Physical Android phone: change it to your laptop's LAN IP, like http://192.168.1.7:8000/api/v1/. Find your IP with ipconfig on Windows or ifconfig on macOS.
• iOS simulator: use http://localhost:8000/api/v1/.

If you changed the IP, also add it to ALLOWED_HOSTS in the Django settings file, and restart the backend server.

Step 10 — Run it

flutter run

First build takes a while. Gradle downloads half the internet. Second run onwards it's fast.

Common Things That Go Wrong

"Connection refused" or "Network error" on the verdict screen

Nine times out of ten this is the base URL in dio_client.dart. Second most likely: you started the backend with runserver without a host, so it's only listening on localhost. For a physical device, run it as python manage.py runserver 0.0.0.0:8000 so it accepts connections from your phone. Also check your laptop's firewall isn't blocking port 8000 — Windows Defender does this silently.

"SECRET_KEY setting must not be empty"

Your .env file either doesn't exist or the key line is blank. Django refuses to start without it. Go back to Step 4.

Camera shows a black screen

Permission wasn't granted. Uninstall the app from the device and reinstall — the permission prompt only appears on first launch, so if you tapped "Deny" once you're stuck until reinstall. Emulators also need their camera set to "Webcam0" in the AVD settings, otherwise there's genuinely nothing to show.

flutter pub get fails with version conflicts

Run flutter clean, then flutter pub get again. If it still fails, check flutter --version — anything below 3.10 will complain about the Dart SDK constraint.

How to Confirm Everything Works

1. Backend running, admin panel loads at /admin/ and shows risk rules.
2. App opens on the scanner screen with a live camera preview.
3. Scan any QR code — a WiFi QR, a website QR, anything. Within a few seconds you should land on a verdict screen with a colour, a score, and a list of findings underneath.
4. Open History. Your scan should be listed there.
5. Kill the backend server and scan again. You should get a graceful offline message rather than a crash, and blacklisted entries should still get flagged from the local cache.

If step 3 gives you a verdict, you're finished. Everything else is just extra confirmation.