Installation Guide

Before You Start

Get these installed first. Doing this now saves you an hour of confusion later.

• Python 3.11 or newer. Grab it from python.org. On Windows, tick the "Add Python to PATH" checkbox during install — if you skip it, every command below fails and you'll be very annoyed.
• Flutter SDK 3.x. From flutter.dev. After installing, run flutter doctor and fix whatever it complains about. Android licence warnings are the usual one.
• Redis. Linux and macOS: your package manager has it. Windows: use Memurai or run Redis inside WSL. Celery won't start without it.
• Chrome or Android Studio. One of the two, to actually run the app.

PostgreSQL is optional. The project falls back to SQLite locally and that's completely fine for your submission.

Step 1 — Backend Setup

Open a terminal inside the project folder and move into the backend.

cd backend
python -m venv venv

Now activate it. Windows:

venv\Scripts\activate

macOS or Linux:

source venv/bin/activate

You'll see (venv) appear at the start of your prompt. That's how you know it worked.

Step 2 — Install and Configure

pip install -r requirements.txt
cp .env.example .env

On Windows use copy .env.example .env instead. Open the new .env file in any editor. For local development you don't need to change a single value — the defaults use SQLite, console SMS and console FCM. Leave it alone and move on.

Step 3 — Database and Demo Data

python manage.py migrate
python manage.py seed_data

The seed command creates donors spread across a city with different blood groups and different last-donation dates. Without it your matching demo returns an empty list and you'll think the code is broken. It isn't. You just have no donors.

Make an admin account too:

python manage.py createsuperuser

Step 4 — Start Redis and Celery

You need three terminals open at once. First one, Redis:

redis-server

Second terminal — activate the venv again, then start the worker:

celery -A raktsetu_backend worker -l info

Third terminal, the scheduler that expires old requests:

celery -A raktsetu_backend beat -l info

On Windows, add --pool=solo to the worker command or it'll throw a permission error.

Step 5 — Run Django

Back in your first backend terminal:

python manage.py runserver

Open http://127.0.0.1:8000/admin/ and log in with the superuser you just made. If you see donors listed there, the backend is done.

Step 6 — Flutter App

New terminal, from the project root:

cd raktsetu_app
flutter pub get

Open lib/core/network/api_config.dart. There's a base URL constant at the top. It defaults to http://10.0.2.2:8000/api/, which is the address an Android emulator uses to reach your host machine — it looks wrong but it's correct for emulators. If you're running in Chrome, change it to http://127.0.0.1:8000/api/. Then:

flutter run

Pick your device when it asks. Chrome is the fastest option for a first check.

Common Problems

"Connection refused" when logging in from the app

Nine times out of ten it's the base URL in api_config.dart. Emulator needs 10.0.2.2, browser needs 127.0.0.1, a real phone on your WiFi needs your laptop's local IP like 192.168.1.x — and for that last one you also have to run Django as python manage.py runserver 0.0.0.0:8000, otherwise it only listens on localhost.

No OTP arrives

It's not being sent anywhere, and that's intentional. Look at your Django terminal — the OTP is printed there. The API response also carries a debug_otp field in dev mode. Copy it from either place.

Nothing happens after creating a request

Your Celery worker isn't running, or Redis isn't. Check that second and third terminal. If the worker logs show notify_nearby_donors_task received and succeeded, the pipeline is alive.

Map shows a blank grey square

Expected until you add a Google Cloud Maps API key. The key slot is already in the Android manifest and web index — you just paste yours in. Location capture through geolocator keeps working regardless, so nothing else is affected.

How to Know It's Actually Working

Do this end of setup, before you show anyone:

1. Register a donor in the app with blood group O-negative and mark them available.
2. Create an emergency request for A-positive at a nearby location.
3. Watch the Celery worker terminal. You should see the matching task fire and pick up your donor, because O-negative is compatible with everything.
4. Watch the Django terminal. The console FCM backend will print the push payload it would have sent.
5. Open the request detail screen in the app and accept it. Status flips to Partially Fulfilled.

If all five happen, you're ready to submit. If step 3 finds no donors, check the donor's availability toggle and their last donation date — anything under 90 days ago and the matcher skips them on purpose.