TrackBack

TrackBack provides a centralized workflow for reporting, matching, claiming, and verifying lost-and-found items across public transport systems. A lost-and-found platform for public transport — riders report items they've lost or found on buses, trains and metro lines, and staff verify claims and hand items back through one dashboard instead of a lost-property notebook.

Built for Problem Statement 24: Lost and Found in Public Transport System.

Screenshots

The screenshots below walk through the complete workflow — registration, lost/found reporting, automatic matching, claiming, admin verification, and public browsing.

1. Account registration

Users create an account with a name, email, optional phone number, and password. A registered account is required to report items, submit claims, and receive notifications.

2. Reporting a lost item

A registered user reports a lost item with a title, category, date, location, description, and an optional photo. More detail means better auto-match candidates.

3. Lost report dashboard

Once submitted, the report shows up in the user's dashboard with its current status.

4. Reporting a found item

Users or transport staff report an item they found with the same set of details — title, category, date found, location, description, and an optional photo.

5. Match detection

TrackBack compares lost and found reports and flags likely matches by category, location, and description/title overlap. Matched reports get linked automatically.

6. Claim submission

When a user recognizes a matched found item as theirs, they submit a claim with "This is mine", which goes to an admin for verification.

7. Admin claim verification

Admins get a console listing pending claims, each with the claimant's info and message, plus approve/reject actions.

8. Public browse

Anyone can search available lost-and-found reports by keyword and category without logging in. Claiming an item requires an account.

Why

Every day, people leave things behind on buses and trains, and just as many people find them with no easy way to report it. Most transit authorities still handle this with a notebook at a lost-property counter.

TrackBack digitizes that: riders file a report in under a minute, the system checks it against existing reports for a possible match, and staff verify the claim before anything is marked returned. The goal is to make the process faster and more transparent for both passengers and transport staff.

Features

• Report lost or found items with category, description, location, date, and an optional photo
• Public keyword search across all reports using MongoDB text search
• Category and location filters to narrow results
• Automatic match suggestions — new reports are scored against open reports of the opposite type on category, location, and description/title overlap
• Claim workflow — users claim a matched found item, admins approve or reject before it's marked returned
• Notifications when a possible match is found or a claim is resolved
• Admin console — review pending claims, update report statuses, see item-type breakdowns
• JWT authentication with separate user/admin roles
• Image uploads for lost and found reports
• Responsive UI across desktop and mobile

Core workflow

Register / Login
       │
       ▼
Report Lost Item ──────────┐
                            │
                            ▼
                      Matching Engine
                            ▲
                            │
Report Found Item ─────────┘
                            │
                            ▼
                      Match Detected
                            │
                            ▼
                    User Claims Item
                            │
                            ▼
                    Admin Reviews Claim
                       ╱          ╲
                  Approve        Reject
                     │              │
                     ▼              ▼
              Item Resolved   Claim Rejected
                     │
                     ▼
              Notification Sent

The system surfaces likely matches automatically, but the final call always stays with a human admin.

Tech stack

Layer	Technology
Frontend	React 18, Vite, React Router
Backend	Node.js, Express
Database	MongoDB, Mongoose
Authentication	JWT, bcrypt
File uploads	Multer
Matching	Custom rule-based heuristic

Project structure

trackback/
├── backend/
│   ├── config/              # Database connection
│   ├── middlewares/         # Auth, admin guard, upload config
│   ├── models/              # User, Report, Claim, Notification
│   ├── routes/              # auth, reports, claims, notifications, stats
│   ├── utils/
│   │   └── matcher.js       # Automatic matching heuristic
│   ├── uploads/              # Uploaded item images
│   ├── seed.js               # Creates the default admin account
│   └── server.js             # Express server
│
├── frontend/
│   └── src/
│       ├── components/       # Navbar, ReportCard, StatusBadge, ProtectedRoute
│       ├── context/          # AuthContext
│       └── pages/            # Home, Login, Register, ReportForm, Dashboard, AdminDashboard
│
├── screenshots/
│   ├── 01-register.png
│   ├── 02-report-lost.png
│   ├── 03-lost-report-dashboard.png
│   ├── 04-report-found.png
│   ├── 05-match-detected.png
│   ├── 06-claim-submitted.png
│   ├── 07-admin-pending-claim.png
│   └── 08-public-browse.png
│
├── .gitignore
├── LICENSE
└── README.md

API reference

All routes are prefixed with /api.

Purpose	Route	Method	Auth
Register	/auth/register	POST	Public
Login	/auth/login	POST	Public
Current user	/auth/me	GET	User
Report a lost item	/reports/lost	POST	User
Report a found item	/reports/found	POST	User
List reports	/reports	GET	User/Admin
Search reports	/reports/search?q=&type=&category=&location=	GET	Public
Get suggested match	/reports/matches/:reportId	GET	User
Update report status	/reports/:id/status	PUT	Admin
Delete a report	/reports/:id	DELETE	Owner/Admin
Submit a claim	/claims	POST	User
List claims	/claims	GET	User/Admin
Approve a claim	/claims/:id/approve	PUT	Admin
Reject a claim	/claims/:id/reject	PUT	Admin
List notifications	/notifications	GET	User
Mark notification read	/notifications/:id/read	PUT	User
Dashboard statistics	/stats	GET	Admin

Getting started

Prerequisites

• Node.js 18+
• MongoDB running locally, or a free MongoDB Atlas cluster
• npm

1. Clone the repository

git clone https://github.com/anujjakhotiya/trackback.git
cd trackback

2. Configure the backend

cd backend
cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env instead.

Update the values in backend/.env:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_secret_key
CLIENT_ORIGIN=http://localhost:5173

Install dependencies, seed an admin account, and start the server:

npm install
npm run seed    # prints the admin login to the terminal
npm run dev     # http://localhost:5000

3. Configure the frontend

In a second terminal:

cd frontend
cp .env.example .env
npm install
npm run dev     # http://localhost:5173

Open http://localhost:5173, register a rider account, and log in. Use the admin credentials printed by npm run seed to reach the admin console at /admin.

Never commit your .env files or real credentials to GitHub — they're already excluded by .gitignore.

How matching works

When a new report comes in, utils/matcher.js pulls open reports of the opposite type in the same category and scores each candidate on:

• Category match
• Location match
• Description/title keyword overlap

If the best candidate clears a minimum threshold, both reports are linked and flagged matched, and both owners get a notification. This is intentionally a small rule-based heuristic rather than machine learning — explainable, and good enough to surface likely pairs for a human to verify, which is the actual workflow transit staff want.

Authentication and authorization

TrackBack uses JWT-based authentication with two roles:

User

• Register and log in
• Report lost or found items
• Search reports
• View their own reports and notifications
• Submit claims

Admin (everything a user can do, plus)

• Review pending claims
• Approve or reject claims
• Update report statuses
• View all reports and dashboard statistics

Protected routes are enforced with requireAuth and requireAdmin middleware on the backend, and a ProtectedRoute wrapper on the frontend.

Claim verification

A detected match never auto-resolves a report — it always goes through a human check:

Potential Match
      │
      ▼
User Submits Claim
      │
      ▼
Admin Reviews Claim
      │
      ▼
Approve / Reject
      │
      ▼
Report Status Updated
      │
      ▼
User Notified

Testing the complete workflow

Use two rider accounts plus the seeded admin account.

Lost item flow

1. Register a user account and log in.
2. Submit a lost-item report.
3. Check the dashboard — the report should appear with status pending.

Found item flow

1. Submit a found-item report with similar category/location/description.
2. Confirm TrackBack flags a potential match.
3. Check the dashboard and notifications for both accounts.

Claim flow

1. Open the matched found item from the Browse page.
2. Select This is mine.
3. Submit the claim.

Admin verification flow

1. Log in as admin.
2. Open Admin → Pending claims.
3. Review the claimant's info and message.
4. Approve or reject.
5. Confirm the report status and claimant's notification update accordingly.

Possible next steps

• Image similarity matching (perceptual hashing) alongside the text heuristic
• Email/SMS notifications instead of in-app only
• Pagination and saved searches on the browse page
• Bulk status updates in the admin console
• Per-station/operator dashboards
• Audit history for admin actions

License

MIT — see LICENSE.

---

Built by Anuj Jakhotiya.