Household Waste Collection Route & User-Fee Manager for Haritha Karma Sena Units (Django REST + React)

Haritha Route & Fee Manager (HRFM) is a web application for the Haritha Karma Sena — the Kudumbashree women's workforce that collects non-biodegradable waste door-to-door across Kerala under Suchitwa Mission guidance, charging each household a small monthly user fee. Every sena worker covers at least 250 houses, keeps a paper fee card per household, and answers to a green supervisor and the local body. The money side is the hardest part: fees arrive in cash across the month, revisions are announced mid-year, households dispute what they paid, and the panchayat wants a monthly statement of fee collection and waste quantity — none of which a notebook can produce.

HRFM gives four actors one shared system: the local-body coordinator defines wards, routes and fee plans; the green supervisor assigns houses to workers and reconciles cash; the worker records each collection round and picks up bulky-waste requests; and the household gets a portal showing its fee ledger, receipts and pickup status. Fee plans are effective-dated, so a revision applies from its notification date without rewriting history; each payment gets a receipt code; and defaulters, route coverage and quantity handed to the clean-up company come out as reports.

The stack is Django 5 with Django REST Framework serving a JSON API and React on the front end, with MySQL 8 behind it — a modern separation that lets the project demonstrate REST design, JWT authentication, role-based access, transaction-safe ledgers and a component-based UI, all defensible line by line in a FYUGP semester-8 viva.

Haritha Karma Sena units collect a monthly user fee from hundreds of households each and gather non-biodegradable waste door-to-door, but the unit's records are paper fee cards, a cash diary and memory. Fees are revised from time to time, so past months, old rates and current arrears blur together; households lose track of what they paid and dispute receipts; houses skipped on a collection day are discovered only when someone complains; bulky-waste pickups are arranged by phone with no request or closure record; and the local body's monthly statement of fee collection and waste quantity is compiled by hand.

The problem is to build a role-based web application that plans routes and households, records each collection round as it happens, keeps a fee ledger whose accruals always cite the fee plan effective on that date, issues receipt codes for every payment, tracks pickup requests to closure, and produces coverage, collection and remittance reports — without storing any government identity numbers.

Abstract

Kerala's Haritha Karma Sena collects non-biodegradable waste from lakhs of households for a monthly user fee — about 47.9 lakh households and 2.57 lakh shops are covered, and local bodies collect crores in user charges monthly. Yet inside a typical unit the work runs on paper fee cards and memory: who paid, who is in arrears, which houses were skipped, how much waste was gathered. This project builds the Haritha Route & Fee Manager (HRFM) — a Django REST Framework backend, a React front end and MySQL — covering ward and route planning, household fee subscriptions, worker-wise collection rounds, an effective-dated fee ledger with receipt codes, bulky-waste pickup requests and coverage, collection and remittance reports.

Introduction

I interviewed a seven-member sena unit in a municipality (name changed) with its green supervisor. Each worker walks fixed streets every collection day, marking rounds in a diary; the supervisor collects each worker's cash, writes it in a ledger and remits it at the local-body office. The fee was revised last year and the unit spent weeks explaining arrears. Households call the worker directly for bulky pickups — old chairs, e-waste — with no record of request or closure. The unit's questions repeat: who has not paid this month, which houses were missed, what quantity went to the handover, and what does each worker's route owe.

Existing system and its limitations

• Paper fee cards and a supervisor's cash ledger — no instant arrears list, no receipt for the household.
• Fee revisions applied by announcement, so old and new rates blur mid-month.
• Collection rounds recorded after the fact, so skipped houses surface only in complaints.
• Bulky-waste pickup requests arrive by phone and are remembered, not tracked.
• Local-body reporting (fee collected, quantity collected) is compiled manually each month.

Proposed system

• Wards, routes and households in a normalised database, with category-based fee plan subscriptions.
• Effective-dated fee plans: a revision takes effect from its date, and every accrual stores the plan it used.
• Worker collection rounds per route-day with picked / refused / absent status and quantity in kg.
• A fee ledger with monthly accruals, cash payments with receipt codes, arrears lists and a supervisor reconciliation view.
• Pickup requests raised by households, scheduled to a worker, closed with a quantity note.
• Dashboards and CSV reports: route coverage, fee collection by ward, handover quantity.
• JWT-secured REST API with role-based access (Coordinator, Supervisor, Worker, Household) and an audit log of financial changes.

Feasibility study

• Technical: Django and React are taught in the FYUGP BCA syllabus (UK5DSECAP307, UK4DSECAP203); MySQL in DBMS (UK3DSCCAP201). DRF provides serializers, authentication and browsable API testing; everything is open-source.
• Economic: one low-cost VPS or the local body's existing server; no licence fees.
• Operational: the worker's screen is one checklist per route-day, usable on a budget phone's browser; households get a read-mostly portal.
• Schedule: 16 weeks — study, design, four build increments, testing, documentation.

In scope

• One local body (municipality or panchayat) with multiple wards, multiple sena units and routes of 200–300 households each.
• Four roles: Local-body Coordinator, Green Supervisor, Sena Worker, Household.
• Household registry (name, address, category home/shop/institution, contact — no Aadhaar or government ID numbers), subscription and exit.
• Fee plans per category with effective dates; monthly accrual; cash payment recording with receipt codes; arrears and defaulters reports.
• Collection rounds per route-day with per-household status and waste quantity in kilograms.
• Bulky-waste pickup requests with scheduling and closure notes.
• Dashboards and CSV exports: route coverage, collection percentage by ward, fee collected, quantity handed over.

Out of scope (v1)

• Online payment gateway; fees are collected in cash by the worker and recorded with a receipt code (a UPI collect flow is future scope).
• GPS tracking of workers and route optimisation algorithms.
• Biodegradable waste and composting workflows, material-recovery-facility operations and weighing-bridge integration.
• A native mobile app (the worker uses the responsive web UI) and multi-local-body tenancy.

The project follows the Incremental SDLC model across 16 weeks: the route and household core ships first, then rounds, then the fee ledger, then reports — each increment demonstrated to the guide. A short field study fixes the vocabulary before design.

Member-wise work split (team of 3). Member 1: backend core — models, JWT auth, roles, wards/routes/households API. Member 2: rounds module and pickup-request workflow, worker screens in React. Member 3: fee-plan versioning, accrual and payment logic, receipts, reconciliation, reports and the test suite. DFDs, ER diagram and the report were prepared jointly.

Fee rule. Each household accrues its plan's monthly rate on the 1st for that month, using the plan version effective on that date (category home/shop/institution). A payment records amount, date, paying household and a system-generated receipt code; part payments are allowed and the ledger balance is the sum of accruals minus payments. A fee revision inserts a new plan version with effective_from; no accrual before that date changes. All money writes run in database transactions and append an audit row.

HRFM is a two-tier client–server web system: a React single-page app talking over HTTPS/JSON to a Django REST Framework API, which owns all business rules and talks to MySQL 8 through Django's ORM.

Component flow

flowchart TD
  HH["Household portal (React)"] -->|HTTPS + JWT| API["Django REST API"]
  WK["Worker round screen (React)"] -->|HTTPS + JWT| API
  SUP["Supervisor & Coordinator dashboards (React)"] -->|HTTPS + JWT| API
  API --> SER["Serializers + role checks"]
  SER --> SVC["Fee ledger / rounds / pickup services"]
  SVC --> ORM["Django ORM"]
  ORM --> DB[("MySQL 8")]
  SVC --> AUD["Audit log"]
  SVC --> RPT["CSV report generator"]

ER diagram

erDiagram
  WARD ||--|{ ROUTE : contains
  ROUTE ||--|{ HOUSEHOLD : covers
  USER ||--o{ AUDIT_LOG : writes
  FEE_PLAN ||--o{ ACCRUAL : "prices"
  HOUSEHOLD ||--o{ ACCRUAL : "is billed"
  HOUSEHOLD ||--o{ PAYMENT : makes
  HOUSEHOLD ||--o{ PICKUP_REQUEST : raises
  WORKER ||--o{ ROUND_ENTRY : records
  ROUTE ||--o{ ROUTE_DAY : schedules
  ROUTE_DAY ||--o{ ROUND_ENTRY : produces
  PICKUP_REQUEST ||--o| ROUND_ENTRY : "closed in"

  WARD {
    int id PK
    string name
    string local_body
  }
  ROUTE {
    int id PK
    int ward_id FK
    string name
    string weekday_pattern
  }
  HOUSEHOLD {
    int id PK
    int route_id FK
    string code UK
    string name
    string address
    string category
    string phone
    boolean active
  }
  FEE_PLAN {
    int id PK
    string category
    decimal monthly_fee
    date effective_from
    date effective_to
  }
  ACCRUAL {
    int id PK
    int household_id FK
    int fee_plan_id FK
    string period_month
    decimal amount
  }
  PAYMENT {
    int id PK
    int household_id FK
    decimal amount
    date paid_on
    string receipt_code UK
    int collected_by FK
  }
  ROUTE_DAY {
    int id PK
    int route_id FK
    date work_date
    boolean closed
  }
  WORKER {
    int id PK
    int user_id FK
    string unit_name
  }
  ROUND_ENTRY {
    int id PK
    int route_day_id FK
    int household_id FK
    int worker_id FK
    string status
    decimal quantity_kg
  }
  PICKUP_REQUEST {
    int id PK
    int household_id FK
    string waste_type
    string status
    datetime raised_at
    datetime closed_at
  }
  USER {
    int id PK
    string username UK
    string password_hash
    string role
  }
  AUDIT_LOG {
    int id PK
    int user_id FK
    string action
    string entity
    datetime created_at
  }

Key design decisions. Fee plans are temporal: each row carries effective_from/effective_to, and an accrual stores a foreign key to the exact plan version it used — this is the cleanest answer to "what rate applied in March after the June revision?". ROUND_ENTRY keys on (route_day, household) so one house cannot be recorded twice in a round, and its status enum keeps coverage computation a simple query. PAYMENT.receipt_code is unique and generated in a transaction with the payment insert, so no two receipts can collide even with two supervisors entering cash simultaneously. The REST API is the only door: every endpoint authenticates with JWT and checks the role, so a household token simply cannot reach the supervisor's reconciliation endpoint, regardless of what the UI shows. Pickup requests are closed by a ROUND_ENTRY, which keeps waste quantities in one place for the handover report.

• UPI collect-request payments from the household portal with automatic ledger matching against the receipt code.
• A worker companion app (Android) with offline round capture that syncs when connectivity returns.
• Route optimisation — ordering households within a route-day to cut walking distance, using the recorded geo-points as future data.
• Integration with material recovery facilities — handover manifests and Clean Kerala Company-style quantity certificates generated directly.
• Analytics for the local body — category-wise compliance, seasonal waste quantity, and predicted defaulters for targeted awareness.
• Multi-local-body tenancy so a district can run every sena unit from one deployment with ward-level data isolation.