Project presentation · ReturnLoop

SOFTWARE ENGINEERING · MINI PROJECT

ReturnLoop

A returns and reverse-logistics centre for an e-commerce business: request, pickup, quality check, grading, refurbish / restock / scrap, refund.

PRESENTED BY04

01Chirag Seervi

02Anshuman Singh

03Aryan Singh

04Aadi Srivastava

FLASK · SQLITE · THREE.JS

02

AGENDA

What we'll cover

03

PPM · PRODUCT / PROJECT PLANNING & MANAGEMENT

Vision, scope and stakeholders

Product vision

Give an online store one place to run every return, from the customer's doorstep to a graded item and a correct refund, with every step on record.

Objectives

Enforce return rules automatically
Grade items A / B / C and route them
Compute refunds exactly, once
Live tracking for the customer

In scope

6 roles, 13-status workflow
Pickup booking, 2 attempts
QC checklist, fraud check
Refurbish & re-inspection
Refund + inventory log
Admin dashboard & flags

Out of scope

Real payments / payment gateway
Passwords & real accounts
Courier API integration

Stakeholders

Customer	returns items, tracks refund
Pickup agent	collects parcels
Warehouse	checks parcels in
QC inspector	grades items
Refurbisher	repairs grade B
Admin	monitors, flags

Team

Chirag Seervi, Anshuman Singh, Aryan Singh, Aadi Srivastava

04

PPM · PROCESS MODEL & PLAN

Incremental delivery in seven increments

Each increment was built, tested with pytest, run, and committed to Git before the next one started. Definition of done: all tests green and the app runs.

INC ACoreModels, config, services, unit tests
INC BDataSeed data through real services
INC CCustomerOrders, return, pickup, tracking
INC DOperationsAgent, warehouse, QC, refurbisher
INC EAdminDashboard, charts, flags
INC FExperienceDesign system, 3D scenes, effects
INC GHardeningEdge cases, docs, end-to-end demo

Why incremental?

Business rules first, UI later: the riskiest logic (state machine, refunds) was tested before any screen existed.

Work breakdown

Data model → services → routes → templates → visual design → testing & docs.

Tools

Python, Flask, SQLite, pytest, Git, VS Code, Playwright for screenshot checks.

05

PPM · RISK & QUALITY MANAGEMENT

Risks, and how we handled them

Risk Impact Mitigation in the product

Invalid status jumps (e.g. refund before QC) High Single state machine; every change validated and logged in status_history

Refund paid twice High Unique refunds.return_id + service check + one DB transaction

Double-clicks on submit Medium Buttons disable on submit; server rejects the repeat via the state machine

Malicious or huge uploads Medium Type, 3 MB size and file-signature checks; random file names

Device without WebGL / slow GPU Low Static fallbacks; particles halve if frame rate < 40 fps

Rules change later (window, fees) Low All rule constants live in config.py

Risk	Impact	Mitigation in the product
Invalid status jumps (e.g. refund before QC)	High	Single state machine; every change validated and logged in `status_history`
Refund paid twice	High	Unique `refunds.return_id` + service check + one DB transaction
Double-clicks on submit	Medium	Buttons disable on submit; server rejects the repeat via the state machine
Malicious or huge uploads	Medium	Type, 3 MB size and file-signature checks; random file names
Device without WebGL / slow GPU	Low	Static fallbacks; particles halve if frame rate < 40 fps
Rules change later (window, fees)	Low	All rule constants live in `config.py`

QUALITY: 109 AUTOMATED TESTS · STATE MACHINE, REFUNDS, ELIGIBILITY, FLAGS, API, PAGES, FULL FLOW

06

REQUIREMENTS

Functional requirements

FR01Role switch

Choose any of 6 roles and a user without a password; each page rejects the wrong role (403).

FR02View orders

Customer sees delivered items with eligibility, or the reason it can't be returned.

FR03Eligibility

Return allowed within 7 days of delivery, for returnable products, with no other open return.

FR04Request return

Reason, comment (≤ 300 chars), optional photo (PNG/JPG/WEBP, ≤ 3 MB).

FR05Book pickup

Date from tomorrow to +5 days, slot Morning / Afternoon / Evening; reschedule.

FR06Collect parcel

Agent marks picked up or absent; the 2nd absence cancels the return.

FR07Receive

Warehouse checks the parcel in; it joins the QC queue.

FR08Inspect & grade

QC checklist, suggested grade, A/B/C; a mismatched item is rejected as fraud.

FR09Refurbish

Grade B goes to repair, then re-inspection: pass → restock (70%), fail → scrap.

FR10Refund

final = max(0, base × grade% − pickup fee), damaged/wrong-item exception, created once.

FR11Track

Live status (polled every 5 s), history timeline and refund breakdown.

FR12Dashboard

Totals, reasons and grades charts, frequent-returner flags (> 3 in 30 days).

FR13Hand off

After each step, a card names the next desk and opens its page in one click.

FR14Repair ticket

QC's findings become the fix list; ticked fixes are saved as the notes; past repairs show QC's verdict.

FR15Live feed

The admin sees the latest status changes, newest first, with who made each one.

07

REQUIREMENTS

Non-functional requirements

NFR01Performance

60 fps on a mid laptop, 30+ on phones; pixel ratio capped; 3D pauses off-screen.

NFR02Reliability

Refund + inventory log + status change in one transaction; no double refunds.

NFR03Security

Role guard on every blueprint; customers only see their own returns; upload validation.

NFR04Usability

Plain-language errors and empty states; the handoff card always names the next step.

NFR05Accessibility

WCAG AA contrast, keyboard-only use, visible focus, reduced-motion mode, text on every badge.

NFR06Maintainability

Logic in services/, rules in config.py, thin routes; a pytest suite over services, pages and the full flow.

NFR07Portability

Python 3.10+, SQLite, no build step: install, seed, run in 3 commands.

NFR08Robustness

Static fallbacks without WebGL or internet; friendly 403 / 404 / 413 pages.

08

UML · USE CASE DIAGRAM

Who does what

09

UML · CLASS DIAGRAM

The domain model (models.py)

classDiagram
  direction TB
  class Customer {
    +name
    +email
    +address
  }
  class Product {
    +name
    +price
    +is_returnable
  }
  class Order {
    +order_date
    +delivered_at
    +total
  }
  class OrderItem {
    +quantity
    +unit_price
  }
  class ReturnRequest {
    +return_code
    +reason
    +status
    +flagged_fraud
  }
  class Pickup {
    +slot_date
    +slot_window
    +attempt_no
  }
  class QCReport {
    +grade
    +item_matches_order
    +is_recheck
  }
  class RefurbishJob {
    +status
    +completed_at
  }
  class Refund {
    +grade_percent
    +pickup_fee
    +final_amount
  }
  class InventoryLog {
    +action
    +quantity
  }
  class StatusHistory {
    +from_status
    +to_status
    +actor_name
  }
  Customer "1" --> "*" Order : places
  Order "1" *-- "1..*" OrderItem : contains
  OrderItem "*" --> "1" Product
  OrderItem "1" --> "*" ReturnRequest : returned in
  ReturnRequest "1" *-- "*" Pickup
  ReturnRequest "1" *-- "*" QCReport
  ReturnRequest "1" *-- "*" RefurbishJob
  ReturnRequest "1" *-- "0..1" Refund
  ReturnRequest "1" *-- "*" StatusHistory
  ReturnRequest "1" --> "*" InventoryLog

10

DFD · LEVEL 0 (CONTEXT DIAGRAM)

The system and the people around it

flowchart LR
  C[Customer]
  AG[Pickup agent]
  WH[Warehouse manager]
  QC[QC inspector]
  RF[Refurbisher]
  AD[Admin]
  S(("0
ReturnLoop
System"))
  C -- "return request, photo, pickup slot" --> S
  S -- "eligibility, status, refund breakdown" --> C
  S -- "pickup list, addresses" --> AG
  AG -- "picked up / absent" --> S
  WH -- "parcel received" --> S
  S -- "inbound parcels, inventory" --> WH
  S -- "QC queue, item details" --> QC
  QC -- "checklist, grade" --> S
  S -- "repair jobs" --> RF
  RF -- "repaired" --> S
  S -- "stats, charts, flagged customers" --> AD

11

DFD · LEVEL 1

Processes and data stores

flowchart LR
  C[Customer]
  AG[Pickup agent]
  WH[Warehouse]
  QC[QC inspector]
  RF[Refurbisher]
  AD[Admin]
  P1(("1.0
Check eligibility
& create return"))
  P2(("2.0
Schedule
pickup"))
  P3(("3.0
Collect
parcel"))
  P4(("4.0
Receive
parcel"))
  P5(("5.0
Inspect
& grade"))
  P6(("6.0
Refurbish"))
  P7(("7.0
Issue
refund"))
  P8(("8.0
Report
& flag"))
  D1[("D1 Orders / Products")]
  D2[("D2 Return requests")]
  D3[("D3 Pickups")]
  D4[("D4 QC reports")]
  D5[("D5 Refunds + Inventory log")]
  D6[("D6 Status history")]
  C -- "reason, photo" --> P1
  D1 -- "delivery date, returnable" --> P1
  P1 -- "new return" --> D2
  C -- "date, slot" --> P2
  P2 --> D3
  D3 -- "pickup list" --> AG
  AG -- "outcome" --> P3
  P3 --> D2
  WH -- "check-in" --> P4
  P4 --> D2
  QC -- "checklist, grade" --> P5
  P5 --> D4
  P5 -- "grade B" --> P6
  D4 -- "QC findings" --> P6
  RF -- "repaired" --> P6
  P6 -- "re-inspection" --> P5
  P5 -- "A / C / recheck" --> P7
  P7 --> D5
  P5 -. "every status change" .-> D6
  D2 & D5 --> P8
  D6 -- "latest events" --> P8
  P8 -- "stats, flags, live feed" --> AD

12

UML · ACTIVITY DIAGRAM

One return, start to finish

13

UML · SEQUENCE DIAGRAM

QC grades a return and the refund is issued

sequenceDiagram
  autonumber
  actor QC as QC inspector
  participant B as Browser
  participant R as qc blueprint
  participant W as services.returns
  participant SM as state_machine
  participant F as services.refund
  participant DB as SQLite
  QC->>B: tick checklist, choose grade A, Stamp it
  B->>R: POST /qc/inspect/RL-2026-0004
  R->>W: submit_inspection(ret, checklist, "A")
  W->>SM: change_status(Received → Inspected)
  W->>SM: change_status(Inspected → Restocked)
  W->>F: issue_refund(ret, "Restocked")
  F->>F: calculate_refund(base, A, reason)
  F->>SM: change_status(Restocked → Refunded)
  F->>DB: INSERT refund, inventory_log, status_history (one COMMIT)
  R-->>B: 302 redirect to queue + toast
  Note over B,DB: Customer's tracking page polls GET /api/return/code/status every 5 s and moves the parcel

14

UML · STATE DIAGRAM

Every status a return can be in

15

UML · SEQUENCE DIAGRAM

Handing a return to the next desk

sequenceDiagram
  autonumber
  actor A as Pickup agent
  participant B as Browser
  participant R as agent blueprint
  participant W as services.returns
  participant H as services.handoff
  participant S as /switch
  participant DB as SQLite
  A->>B: Mark picked up, confirm
  B->>R: POST /agent/pickup/7
  R->>W: mark_picked_up(pickup)
  W->>DB: status Picked Up + history row (COMMIT)
  R->>R: hand_off(ret): remember RL-2026-0004 in the session
  R-->>B: 302 redirect to /agent/pickups
  B->>R: GET /agent/pickups
  R->>H: handoff_for(ret, agent) while rendering
  H-->>R: next desk: warehouse, Ansuman Singh
  R-->>B: page + card "Your part is done"
  A->>B: Continue as warehouse
  B->>S: POST /switch (who, next, code)
  S-->>B: 302 redirect to /warehouse/receive?focus=RL-2026-0004
  Note over B,DB: The warehouse page opens with this parcel highlighted. No menu, no searching.

16

ARCHITECTURE · LAYERS

Layered architecture

L1 Presentation Jinja2 templates · main.css · ES modules · Three.js scenes · GSAP · Chart.js templates/, static/

L2 Controller / routing Flask blueprints, one per role + JSON API; role guard on each blueprints/

L3 Business logic Workflow, state machine, eligibility, refund, flags, uploads, stats services/

L4 Configuration Every business rule as a named constant (window, fees, %, limits) config.py

L5 Data access Flask-SQLAlchemy ORM: 11 model classes and their relationships models.py

L6 Persistence SQLite database file, indexes on status, customer, history returnloop.db

RULE: EACH LAYER ONLY TALKS TO THE ONE BELOW · ROUTES NEVER CONTAIN BUSINESS RULES

17

ARCHITECTURE · FROM UI TO DATA

One click, layer by layer: “Request return”

UIBrowser
Form with reason tiles, comment and photo is submitted (button disables itself).
HTTPPOST /customer/return/new
Multipart request reaches Flask; session holds role + user id.
Guardcustomer blueprint
before_request checks the role is customer, else friendly 403.
Validateservices.uploads
Photo type, size ≤ 3 MB and file signature are checked.
Rulesservices.eligibility
7-day window, returnable product, no open return.
Logicservices.returns
Generates RL-2026-0004, writes the first status_history row.
ORMmodels.ReturnRequest
SQLAlchemy turns objects into INSERT statements.
DataSQLite
Rows committed in one transaction.
Back to UIRedirect + Jinja2
Pickup page renders; tracking page later polls the JSON API.

END OF DECK · QUESTIONS?

Thank you.

Chirag Seervi · Anshuman Singh · Aryan Singh · Aadi Srivastava

pip install -r requirements.txt && python seed.py && python app.py

ReturnLoop, the software engineering view