City Bus Pass Renewal and Concession Management System (React + Spring Boot + MySQL)

City Bus Pass Renewal and Concession Management System is a full-stack web application for a fictional tier-2 city transport corporation — we call it Kaveri City Transport — built for the situation every Indian commuter knows: joining the monthly queue at the pass counter, filling the same form again after the pass expires, and hoping the conductor believes the laminated card is still valid.

The system gives citizens a portal to register once, apply for a pass in a concession category (student, senior citizen, differently-abled or general), upload the supporting document, pay the fee by recording a UPI or counter-payment reference, and download a pass carrying a QR code. Counter clerks verify documents and approve or reject applications with a reason; conductors scan the QR on boarding and the system answers instantly whether the pass is valid — with every check logged. Renewal reuses the citizen's data: three clicks and a payment reference, no re-typing. Admins manage pass categories, concession percentages, routes and reports (passes issued, revenue by category and route, expiry due-lists).

The application is built exactly on the C-20 Full-Stack pathway: React 18 with TypeScript on the front end, Spring Boot 3 with Spring Data JPA serving a REST API, MySQL 8 as the database, JWT-based authentication with BCrypt-hashed passwords, and JUnit 5 and Postman covering the tests. It demonstrates role-based access control, transactional renewal logic, QR generation and audit logging — a viva-defensible slice of real public-transport administration.

A tier-2 city transport corporation issues thousands of monthly and quarterly bus passes, yet the process is almost entirely manual: paper forms, registers, hand-written receipts and a printed card whose validity the conductor cannot verify at the door. Citizens re-apply from scratch every cycle and queue at the counter; concession eligibility is judged from photocopies with no recorded decision; expired or tampered passes ride for free; and the office learns its own revenue only at month end, counted by hand. The corporation needs a secure, role-based web system that lets citizens apply and renew online, enforces configurable concession rules with an audit trail, gives conductors instant QR-based verification, records payments transactionally, and produces revenue and expiry reports on demand — without storing government ID numbers.

Abstract

City bus corporations sell thousands of passes a month, and in most tier-2 cities the work is still manual: paper forms, register entries, counter queues and passes whose validity a conductor can only guess at. This project delivers a role-based web system for pass applications, concession handling, QR-verified boarding, renewals and reporting, built with React, Spring Boot and MySQL following the C-20 Full-Stack pathway.

Introduction

A city transport corporation's pass office is its busiest public counter. The queue exists because the process is re-verification from scratch: the same citizen re-fills the same details every month or quarter, the clerk re-enters them into a register, concession eligibility is judged by eye from photocopies, and revenue reporting means counting pages at month end. Karnataka's larger corporations have digital passes; a smaller city corporation needs something simpler and cheaper that still covers applications, concessions, verification and renewals properly. That is the system we built.

Existing System

• Applications are paper forms; details are re-entered into a register for every renewal.
• Concession eligibility is checked from photocopied documents with no recorded decision trail.
• The pass is a printed card; a conductor cannot reliably tell valid from expired or tampered at the door.
• Payments are receipted by hand; revenue reports are compiled manually by category and route.
• Limitations: repeated queues, no audit trail, concession leakage, no near-real-time reporting, and no way to remind citizens before expiry.

Proposed System

• Citizen portal: one-time registration with mobile number, document upload, application tracking through approval, and expiry reminders on the dashboard.
• Concession engine: concession percentages are admin-configurable rules, not hard-coded values; the clerk's approval is logged with their user id.
• QR pass: each pass carries a QR encoding the pass number; the conductor's page resolves it against the server and shows validity and category, and every scan is logged.
• Payments: payment is recorded with a channel (counter or UPI reference); a pass becomes Active only on confirmed payment, recorded transactionally.
• Renewal: a renewal reuses stored citizen data, requires a fresh payment reference and (for students) a current bonafide, and issues the new pass in one transaction.
• Reports: passes issued, revenue by category and route, expiry due-list and concession-leakage summary, exportable as CSV.
• Privacy by design: the system stores no government ID numbers — identity is a phone number and the documents the corporation actually needs.

Feasibility Study

• Technical: the entire stack — React, Spring Boot, Spring Data JPA, MySQL, JUnit, Postman — is the C-20 Full-Stack pathway toolset; QR generation uses the open-source ZXing library; everything runs on one lab PC or a small cloud instance.
• Economic: zero licence cost; the corporation's existing office PC and internet connection are enough, and counter staff already handle worse software.
• Operational: citizens need only a phone with a browser; clerks need a half-hour orientation; the conductor flow is a single scan-and-answer screen designed for one-handed use between stops.

In scope

• One fictional corporation (Kaveri City Transport) with multiple routes, pass categories, counter clerks, conductors and an administrator.
• Citizen registration, application, document upload, approval workflow, payment recording, QR pass issue, conductor verification, renewal and reports.
• Role-based access control, audit logging of approvals and scans, CSV exports, and JUnit/Postman test evidence.

Out of scope (v1)

• No online payment gateway — payments are recorded with a UPI reference or counter receipt, which keeps the demo offline-safe.
• No offline conductor verification (the v1 verification endpoint requires connectivity; a cached-validation PWA is future work).
• No GPS tracking, route planning or ticketing for cash passengers; no SMS/email gateway (reminders are shown on the dashboard).
• No biometric authentication and no storage of government ID numbers — by design, not omission.

The project follows an iterative (incremental) SDLC model across the 16-week slot: three increments, each ending in a demonstrable system, with reviews mapped to the C-20 schedule.

Testing approach: JUnit 5 covers the service layer — concession calculation, renewal transaction consistency, payment-to-activation rule, duplicate-pass prevention. Postman exercises every REST endpoint including negative cases (expired token, wrong role, double payment). Each screen has a black-box test-case row (ID, input, expected, actual, status), and a user-acceptance round is run with classmates acting as citizens and a conductor, using the seeded demo data.

The system is a classic three-tier full-stack application: a React single-page front end, a Spring Boot REST API, and a MySQL database, secured by a JWT-based stateless auth layer.

flowchart LR
  C["Citizen / Clerk / Admin browser"] -->|"HTTPS"| R["React 18 SPA (TypeScript)"]
  K["Conductor phone"] -->|"HTTPS"| R
  R -->|"REST + JWT header"| A["Spring Boot REST API"]
  A --> S["Spring Security filter chain"]
  S --> L["Service layer: concession rules, renewal, verification"]
  L --> J["Spring Data JPA"]
  J --> DB[("MySQL 8")]
  L --> Q["ZXing QR generator"]
  L --> AU["Audit log of approvals and scans"]
  DB --> RPT["CSV report export"]

Presentation tier. The React SPA renders role-specific dashboards, guards routes by role claim from the JWT, and keeps API calls in a typed client so a changed endpoint fails at compile time, not in the demo.

Application tier. The API exposes resources (citizens, applications, passes, payments, verifications, reports). The service layer owns the business rules: the concession engine reads percentages from the category table; activation and renewal run inside @Transactional methods so a payment and a pass state can never disagree; and every approval or QR scan is appended to the audit log with the acting user and timestamp.

Data tier. The schema is normalised to 3NF with the constraints that make wrong states impossible:

erDiagram
  CITIZEN ||--o{ APPLICATION : submits
  APPLICATION }o--|| PASS_CATEGORY : "belongs to"
  APPLICATION ||--o| PASS : "issued as"
  APPLICATION ||--o{ PAYMENT : "is paid by"
  PASS ||--o{ VERIFICATION_LOG : "generates"
  OFFICE_USER ||--o{ APPLICATION : reviews
  CITIZEN {
    int id PK
    string mobile UK
    string email
    string full_name
  }
  PASS_CATEGORY {
    int id PK
    string name
    int concession_percent
    boolean needs_bonafide
  }
  APPLICATION {
    int id PK
    int citizen_id FK
    int category_id FK
    string status
    datetime applied_at
  }
  PASS {
    int id PK
    int application_id FK
    string pass_no UK
    date valid_from
    date valid_to
  }
  PAYMENT {
    int id PK
    int application_id FK
    decimal amount
    string channel
    string reference
  }
  VERIFICATION_LOG {
    int id PK
    int pass_id FK
    datetime scanned_at
    string result
  }
  OFFICE_USER {
    int id PK
    string username UK
    string role
  }

Pass lifecycle. The state machine below is enforced in the service layer, so no pass can become Active without a confirmed payment, and a rejection always carries a reason:

flowchart TD
  A["Application submitted"] --> B["Under review (clerk)" ]
  B -->|"Approved"| C["Awaiting payment"]
  B -->|"Rejected with reason"| X["Closed"]
  C -->|"Payment recorded + confirmed"| D["Pass issued, QR generated, Active"]
  D -->|"Validity ends"| E["Expired — renewal reuses citizen data"]
  E -->|"Renewal approved + paid"| D

Why these choices. MySQL for relational integrity and the transactions the renewal logic depends on; Spring Boot for a testable, convention-driven API the pathway already teaches; JWT so the conductor's phone needs no server-side session; QR rather than NFC because every conductor already carries a phone camera and printed passes still work as a fallback.

• Online payments through a UPI gateway with automatic reconciliation and receipts.
• Offline-capable conductor verification (PWA with cached pass data and server sync) for routes with patchy connectivity.
• SMS/WhatsApp expiry reminders and renewal links for citizens who do not revisit the portal.
• Route-wise occupancy analytics from verification scans to help schedule extra buses on peak corridors.
• Inspector mode with a fine workflow for invalid passes, closing the enforcement loop.
• Multi-corporation (multi-tenant) deployment so smaller corporations can share one hosted instance.