Product Architecture

01 · Foundation

Product Overview

ISCO TMS is an enterprise transportation management platform for university bus operations. It is delivered as three role-specific clients sharing one backend, one identity layer, and one design system. The architecture is modular so future modules can be added without restructuring navigation or data ownership.

Student App

Mobile · iOS / Android

Booking, QR pass, subscriptions, bookings history, complaints, announcements.

Supervisor App

Mobile · iOS / Android

Attendance (QR / phone / offline), daily schedule, expenses, non-subscribers, revenue.

Admin Dashboard

Web · Responsive

Full CRUD, trip templates, scheduling, analytics, complaints triage, reports, settings.

Architecture Principles

SINGLE SOURCE OF TRUTH

Admin owns the operational data

All departure schedules originate from reusable Trip Templates.
Students consume schedules; supervisors execute trips; neither creates them.
Bus assignment is system-driven, never a student choice.

OFFLINE-FIRST

Field operations never block on network

QR attendance and expense capture work fully offline.
A local queue persists actions and syncs automatically on reconnect.
Conflict rules guarantee one departure scan + one return scan.

ROLE ISOLATION

Least-privilege by design

Each role has a dedicated app surface and permission scope.
Supervisor capabilities are gated by Admin-granted permissions.
Anonymous complaints strip identity before reaching Admin triage.

SCALABLE

Modular for future versions

Navigation reserves slots for new modules (e.g. Live Tracking, Parent App).
Each module is a self-contained feature with its own screens and permissions.
Shared design system keeps new modules visually consistent.

02 · Foundation

System Map

A high-level map of clients, the shared platform services they depend on, and the direction of data flow. Admin writes the operational model; Student and Supervisor apps read and append transactional events.

CLIENTS

Student App (mobile)
Supervisor App (mobile)
Admin Dashboard (web)

PLATFORM SERVICES

Identity & Access (roles)
Scheduling & Trips engine
Payments & Subscriptions
Notifications & Announcements
Offline Sync & Attendance ledger

DATA OWNERSHIP

Admin writes: routes, templates, trips, users, packages, announcements.
Student appends: bookings, complaints, payments.
Supervisor appends: attendance, expenses, non-subscriber records.

Direction of authority

Configuration flows downward (Admin → Supervisor/Student). Operational events flow upward(Supervisor/Student → Admin analytics & reports). No client can mutate another client's authoritative data.

03 · Foundation

Module Inventory

Every capability in the platform grouped into functional modules. Ownership tags indicate the primary actor. The reserved Future Modules branch shows where the architecture is designed to grow.

ISCO TMS Platformv1.0
- Identity & Access
  - Authenticationshared
  - Role selectionshared
  - Profiles & guardians
- Operations
  - Universities & Destinationsadmin
  - Routesadmin
  - Trip Templatesadmin
  - Trips (scheduled instances)admin
  - Drivers · Buses · Supervisorsadmin
- Ridership
  - Bookingstudent
  - QR Passstudent
  - Attendance ledgersupervisor
  - Non-subscriberssupervisor
- Commerce
  - Packages & Subscriptions
  - Payments
  - Expensessupervisor
- Engagement
  - Announcementstargeted
  - Complaintsanon-capable
  - Notifications
- Intelligence
  - Analytics & Chartsadmin
  - Reports (PDF / Excel)admin
- Future Modulesreserved
  - Live Tracking / GPS
  - Parent / Guardian App
  - Driver App
  - Multi-company tenancy

04 · Foundation

Roles & Permissions

The authoritative capability matrix. Supervisor 'Limited' cells are conditional and controlled by Admin-granted permissions — for example managing return trips is only available when Admin enables it for that route.

Capability	Student	Supervisor	Admin
Book departure time	Full	None	None
View own QR pass	Full	None	None
View bus schedule	View	View	Full
Scan / record attendance	None	Full	View
Create departure schedules	None	None	Full
Manage return trips	None	Limited	Full
Record expenses	None	Full	View
Record non-subscribers	None	Full	View
Submit complaint	Full	None	None
Triage / resolve complaints	None	None	Full
Send announcements	None	None	Full
View announcements	View	Limited	Full
Manage users (CRUD)	None	None	Full
View analytics & reports	None	None	Full

FullCreate, read, update, delete

ViewRead-only access

LimitedConditional / permission-gated

NoneNo access to capability

05 · Navigation

Navigation Model

Navigation is role-driven and platform-appropriate. Mobile clients use a persistent bottom tab bar with a maximum of five primary destinations; overflow lives inside a hub screen. The Admin web dashboard uses a collapsible left side-nav with grouped sections.

STUDENT · MOBILE

Bottom Tab Bar

5 tabs. Task-focused around booking and the QR pass.

SUPERVISOR · MOBILE

Bottom Tab Bar

5 tabs. Attendance-first, optimized for on-bus use.

ADMIN · WEB

Grouped Side Nav

Collapsible sections for dense operational management.

Five-tab rule

Mobile primary navigation never exceeds five destinations. Secondary features (Profile, Announcements, Complaints) are reached from a tab, the dashboard hub, or the header — never added as extra tabs.

06 · Navigation

Student — Bottom Navigation

Five primary tabs. Home is the hub that surfaces everything else (announcements, profile, subscription). The QR tab is centered and elevated because it is the most frequent in-transit action.

Student — Tab Bar5 tabs

Home

Schedule

QR Pass

Bookings

Profile

Secondary destinations (not tabs)

Announcements Complaints Payments Book Trip (CTA)

07 · Navigation

Supervisor — Bottom Navigation

Attendance is the centered, elevated primary action because it is used constantly during boarding. Schedule is read-only for departures. Expenses and Riders round out the daily operational needs.

Supervisor — Tab Bar5 tabs

Dashboard

Schedule

Attendance

Expenses

Riders

Secondary destinations (not tabs)

Non-subscribers Announcements Profile

08 · Navigation

Admin — Side Navigation

A grouped, collapsible left rail organized by domain rather than a flat list. Groups map directly to the module inventory, so new modules slot into an existing group or add a new one without disrupting muscle memory.

Admin Dashboard — Left Rail

Overview

Dashboard & Analytics

People

Students

Supervisors

Drivers

Operations

Routes

Universities

Destinations

Trip Templates

Trips

Commerce

Packages

Payments

Engagement

Announcements

Complaints

Insights

Reports

Exports (PDF / Excel)

System

Settings

09 · Screen Map

Auth & Onboarding

A single shared entry funnel resolves the user into one of three role contexts. Account type selection determines which app surface, navigation, and permission scope load after authentication.

1Splash Screen

Brand load + session/token check.

2Login

Credentials. Handles error, lockout, and forgot-password paths.

3Select Account TypeBranch

Student · Supervisor · Admin. Skipped if the account is bound to a single role.

4Role Dashboard

Loads the role-specific shell, navigation, and permissions.

Edge cases handled at the funnel

Invalid credentials, expired session, no network at launch (fall back to cached session), role mismatch, and a suspended account are all resolved before any dashboard renders.

10 · Screen Map

Student Screen Hierarchy

Parent and child screens for the Student app. The Home Dashboard is a hub that deep-links into every other area. Booking is a guided flow; QR Pass is offline-capable.

Student Approot
- Home Dashboardhub
  - Student name & current route
  - Subscription status widget
  - Payment status widget
  - Remaining trips + next trip
  - Latest announcement preview
  - Quick actions: Book · QR · Bookings · Complaints
- Schedule
  - Departure & arrival times
  - Stations list
  - Available seats indicator
- Book Tripflow
  - Select departure time (only)
  - System assigns bus + driver + supervisor
  - Confirmation + booking receipt
- QR Passoffline
  - Unique student QR
  - Trip balance
  - Subscription status
  - Ride count
- My Bookings
  - Upcoming
  - Completed
  - Cancelled
- Complaints
  - New complaint
  - Anonymous vs Normal toggle
  - Complaint history & status
- Announcements
  - List
  - Detail
- Profile
  - Personal information
  - Subscription information
  - Payment information
  - Guardian information

11 · Screen Map

Supervisor Screen Hierarchy

The Supervisor app is execution-focused. Schedules are read-only for departures; return-trip management appears only when Admin grants the permission. Attendance is the operational core and works offline.

Supervisor Approot
- Dashboardhub
  - Today's riders
  - Today's revenue
  - Expenses
  - Balance
- Scheduleread-only
  - Today's assigned trips
  - Return trip managementif permitted
- Attendanceoffline
  - QR scan (departure / return)
  - Phone number search
  - Offline attendance queue
  - Sync status indicator
- Expenses
  - Fuel
  - Cleaning
  - Driver expenses
  - Other
- Non-subscribers
  - Record passenger
  - Phone + paid amount
- Announcementsroute-scoped
  - Announcements for assigned routes only
- Profile
  - Personal & assignment info

12 · Screen Map

Admin Screen Hierarchy

The most complex surface. Trip Templates are the pivotal concept: Admin authors reusable schedules once, then instantiates Trips from them rather than rebuilding a schedule every day.

Admin Dashboardroot
- Analytics Homehub
  - KPIs: students, supervisors, drivers, routes, trips
  - Revenue · Expenses · Profit
  - Subscriptions & expired subscriptions
  - Charts: by university, by route, revenue, trips, occupancy
- People
  - Students — CRUD, search, filters, QRCRUD
  - Supervisors — CRUD, assign routeCRUD
  - Drivers — CRUD, phone, notesCRUD
- Operations
  - Universities
  - Destinations (From → To)
  - Routes
  - Trip Templates — reusable schedulesreusable
  - Trips
    - Departure time
    - Route + destination
    - Driver + supervisor + bus
- Commerce
  - Packages
  - Payments
- Engagement
  - Announcements — one / multiple / all routestargeted
  - Complaints — view, assign, resolve, close
- Insights
  - Reports — PDF
  - Reports — Excel
- Settings
  - System configuration & permissions

13 · Core Flows

Booking Flow

The defining product rule: a student books a departure TIME, never a specific bus. The system resolves the time slot to the correct bus (and its driver + supervisor) based on capacity and route assignment.

1Open Book Trip

From Home quick action or the Schedule screen.

2Select departure time

e.g. 7:00 AM. Student sees only time slots, seats, and stations.

3System assigns busAutomatic

Engine matches the slot to Bus A / B / C by capacity & route, attaching driver + supervisor.

4Validate eligibility

Checks active subscription, remaining trips, and seat availability.

5Confirm booking

Booking created, trip balance decremented, receipt issued.

DECISIONAt validation: is the student eligible?

Eligible

Active subscription + remaining trips + seat available → booking confirmed.

Blocked

Expired subscription, zero balance, or full slot → show reason + resolution (renew / pick another time).

Why time-based booking

Decoupling students from specific buses lets Admin rebalance vehicles, drivers, and supervisors operationally without invalidating a single booking. The student's contract is with the time slot, not the asset.

14 · Core Flows

Attendance Flow

Supervisors record ridership on the bus using QR, phone search, or offline capture. The controlling invariant: exactly one departure scan and one return scan per student per trip — duplicates are rejected.

METHOD 1

QR Scan

Scan student QR pass
Works fully offline
Fastest during boarding

METHOD 2

Phone Search

Search by phone number
Fallback when QR unavailable
Manual confirm

METHOD 3

Offline Capture

Queued locally
Auto-syncs on reconnect
No connectivity required

Scan lifecycle

1Scan / lookup student

2Check trip legRule

Departure or Return?

3Validate duplicate

Reject if this leg already scanned.

4Record attendance

Write to ledger (local or synced).

DECISIONDuplicate scan on the same leg?

First scan

Departure or return recorded; rider count updates.

Repeat scan

Blocked with a clear "already scanned" message — no double counting, no double charge.

15 · Core Flows

Offline Sync Flow

Field devices must function without connectivity. Attendance and expense actions write to a durable local queue and reconcile with the server automatically when the network returns, with deterministic conflict handling.

1Action performed offline

QR scan / expense / non-subscriber recorded on device.

2Write to local queue

Persisted durably with a client timestamp and idempotency key.

3Detect connectivity

Background listener watches for network availability.

4Auto-sync queueAutomatic

Batched upload in order; server dedupes by idempotency key.

5Reconcile & confirm

Server acknowledges; local items marked synced; UI badge clears.

DECISIONConflict on sync (e.g. duplicate leg from two sources)?

No conflict

Queued items commit as-is and are removed from the local queue.

Conflict

One-scan-per-leg rule wins; the earliest valid scan is kept, later duplicates discarded and reported.

Sync status is always visible

The Attendance screen shows a persistent indicator: number of pending items, last sync time, and a manual "sync now" affordance. The supervisor is never left guessing whether data landed.

16 · Core Flows

Complaint Flow

Students can raise complaints in Normal or Anonymous mode. Anonymous complaints strip identifying data before they reach Admin. Admin then triages through a defined state machine.

DECISIONComplaint mode selected by student

Normal

Attached to student identity; supports follow-up and status notifications back to the student.

Anonymous

Identity removed at submission; Admin sees content only, cannot trace or reply to a person.

Admin triage state machine

1View

New complaint lands in the queue.

2Assign

Route to owner / team.

3Resolve

Action taken & documented.

4Close

Final state; metrics recorded.

Privacy guarantee

Anonymity is enforced at write time, not display time. No audit trail links an anonymous complaint to a student record — even for Admin.

17 · Core Flows

Announcement & Notification Flow

Admin composes an announcement and targets one route, multiple routes, or all routes. Delivery fans out to the students on those routes and to supervisors assigned to them.

1Admin composes

Title, body, and optional priority.

2Select targetTargeting

One route · multiple routes · all routes.

3Resolve audience

Expand routes → students + assigned supervisors.

4Fan-out delivery

Push notification + in-app inbox entry.

5Surface in clients

Student Home preview + Announcements list; Supervisor route-scoped list.

STUDENT

Receives on assigned route

Latest announcement preview on Home
Full list + detail screen
Push notification

SUPERVISOR

Route-scoped only

Sees announcements for assigned routes only
No cross-route visibility

18 · Core Flows

Admin Workflow

The setup-to-operate lifecycle. Admin configures the operational model once (foundational data + reusable templates), then runs daily operations by instantiating trips rather than rebuilding schedules.

One-time / periodic setup

1Universities

2Destinations

From → To

3Routes

4People & Buses

Drivers, supervisors, students

5Trip TemplatesReusable

Reusable schedules

Daily operation (no schedule rebuild)

1Instantiate Trips

From templates

2Assign resources

Driver · supervisor · bus

3Monitor

Live occupancy, revenue, attendance

4Report

Export PDF / Excel

Templates eliminate daily rework

Because schedules are authored once as templates, daily operations reduce to instantiation + assignment. This is the core scalability lever of the Admin experience.

19 · System

Screen & Data Dependencies

Relationships that constrain build order and runtime behavior. Upstream entities must exist before downstream screens are usable, which also defines a natural implementation sequence.

Trip TemplatesTrips

A trip cannot exist without a template.

RoutesTrip Templates

Templates are authored against a route.

TripsBooking

Students book time slots that resolve to trips.

BookingAttendance

Attendance validates against an active booking / subscription.

SubscriptionQR Pass

QR pass reflects live subscription + balance.

Route assignmentAnnouncements

Announcement audience is derived from routes.

Attendance + ExpensesAnalytics

Reports aggregate operational events.

Implementation order follows dependencies

Build foundational operations first (Universities → Destinations → Routes → Templates → Trips), then ridership (Booking → QR → Attendance), then commerce, engagement, and finally analytics that aggregate everything upstream.

20 · System

Error & Empty States

Every screen must define its non-happy-path states. These are first-class deliverables, not afterthoughts — each state has a clear message and a recovery affordance.

Empty

state

No bookings, no complaints, no trips yet.

"No upcoming trips — book your first ride."

Offline

state

Device lost connectivity.

Banner: "Offline — attendance will sync automatically."

Error

state

Action failed or server error.

Inline error + retry, never a dead end.

Loading

state

Data in flight.

Skeletons matching final layout.

Blocked / Denied

state

Permission or eligibility failure.

"Subscription expired — renew to book."

Success / Confirmed

state

Action committed.

Confirmation + receipt / next step.

21 · System

Business Rules

The invariants every client and service must enforce. These are non-negotiable and drive validation, permissions, and conflict resolution across the platform.

1QR attendance works fully offline.

2Offline data syncs automatically on reconnect.

3Phone-number attendance is an allowed fallback.

4Exactly one departure scan per student per trip.

5Exactly one return scan per student per trip.

6A student books a departure time only — never a specific bus.

7The system assigns the bus, driver, and supervisor.

8Admin controls all departure schedules.

9Supervisors have limited, permission-gated capabilities.

10Supervisors manage return trips only if Admin permits.

11Trip Templates are reusable; schedules are not rebuilt daily.

12Announcements can target one, multiple, or all routes.

13Complaints support an anonymous mode with identity stripped at write time.

22 · System

Scalability & Roadmap

The architecture is intentionally modular. New modules attach to an existing navigation group and reuse the shared design system and identity layer, so growth does not require restructuring.

Reserved future modules

NEAR-TERM

Operational depth

Live GPS tracking & ETA for students and Admin
Driver App (separate role surface)
In-app payments & auto-renew subscriptions
Push-based real-time occupancy

LONG-TERM

Platform expansion

Parent / Guardian companion app
Multi-company tenancy (SaaS)
Configurable roles & permission builder
Advanced BI & predictive demand analytics

Extension pattern

Each new module = a data domain + its screens + a permission scope + a navigation slot. The role matrix, side-nav groups, and module inventory are all designed to absorb these additions without breaking existing flows.