Trip Monitoring Docs by binh-dam-ibigroup · Pull Request #374 · ibi-group/otp-middleware

binh-dam-ibigroup · 2026-04-13T20:56:09Z

Checklist

Appropriate branch selected (all PRs must first be merged to dev before they can be merged to master)
Any modified or new methods or classes have helpful JavaDoc and code is thoroughly commented =
The description lists all applicable issues this PR seeks to resolve
The description lists any configuration setting(s) that differ from the default settings
All tests and CI builds passing

Description

This PR adds a new markdown file that provides an overview of trip monitoring.

br648

This is good! A couple of comments to consider.

br648 · 2026-04-14T08:49:15Z

+- **Padding/slack before, between, and after transit legs** (boarding, transfer, alighting slack, respectively)<br>
+These constants ensure a traveler has enough time to exit a vehicle and go to the boarding location
+of the next transit vehicle (see diagram below). OTP-middleware can guess the boarding and alighting slacks
+from the original itinerary, however if an overall transfer slack is configured in OTP, it must also be configured in


Where under OTP should this be checked and is the parameter the same name? Is it possible to get this value from the response to avoid a mismatch in values?

I added clarification in 658e206, thank you. The transfer slack is tough because we don't know whether an itinerary with transfers has the shortest allowable transfers or not.

br648 · 2026-04-14T08:55:22Z

+
+#### Plan Method
+
+If the leg id method fails, a `plan` GraphQL query is sent to OTP to replan the entire trip for the target date, using


It might be worth adding why the leg id method might fail.

Yes, added in 6f5e651

Improve section on slacks

alec-georgoff

One nit! This is awesome, thanks for putting the time into this :D

alec-georgoff · 2026-04-15T17:38:59Z

+
+The **target date** (`MonitoredTrip.journeyState.targetDate`) is the date a trip is supposed to take place.
+For one-time trips, the target date is simply the date of the trip. For recurring trips, the target date is the next
+occurrence of the trip, based on the days the trip is being monitored. Note that holidays are not supported yet.


nit: I might break out the note about holidays into a separate block so it's more noticeable if someone is skimming? Maybe something like this:

Note
Holidays are not yet supported for trip monitoring

Didn't see that feature in the GH docs, very cool! (dd4ac78)

Add notes sections

Fix notes sections

josh-willis-arcadis

Looks good as is. Some comments about adding more information to the current class diagrams and potential for more class diagrams. This would help clearly show the relationship between all the classes and their methods. I think these would be nice to haves.

josh-willis-arcadis · 2026-04-20T18:45:50Z

+---
+title: Trip Monitoring Classes and Relevant Fields/Methods
+---
+classDiagram


A nice addition to this class diagram could the specific methods in each class that are relevant to the trip monitoring process.

josh-willis-arcadis · 2026-04-20T18:59:40Z

+[`MonitorAllTripsJob`](../src/main/java/org/opentripplanner/middleware/tripmonitor/jobs/MonitorAllTripsJob.java)
+that runs every minute in the background. The job splits the monitoring of all qualifying trips between threads
+as determined by the number of CPUs on the instance. Each thread runs a
+[`TripAnalyzer`](../src/main/java/org/opentripplanner/middleware/tripmonitor/jobs/TripAnalyzer.java)


would love to see class diagrams for these at some point!

I will delay implementing this suggestion. Right now, the flow diagram below better explains how the analyzers are set up.

josh-willis-arcadis · 2026-04-20T19:05:40Z

+---
+flowchart LR
+    job["⏱️ MonitorAllTripsJob"]
+    analyzer1[TripAnalyzer<br>CheckMonitoredTrip]


add CheckMonitoredTrip.run() to show which method in the class diagram was called.

Updated in da5dbc0

josh-willis-arcadis · 2026-04-20T19:14:49Z

+| `PLAN_QUERY_RESOURCE_URI` | Optional location of a custom GraphQL template for the OTP `plan` query.  |
+| `MAXIMUM_MONITORED_TRIP_ITINERARY_CHECKS` | The maximum number of attempts to obtain a matching itinerary (default 3). Used with `MonitoredTrip.attemptsToGetMatchingItinerary`. |
+
+The [`ItineraryExistence`](../src/main/java/org/opentripplanner/middleware/models/ItineraryExistence.java) class


these are methods that could be added to the class diagram.

Added in fe2b038

josh-willis-arcadis · 2026-04-20T19:18:32Z

+
+#### Leg ID Method
+
+The [`ItineraryChecker`](../src/main/java/org/opentripplanner/middleware/itinerarymatching/ItineraryChecker.java) class


Would love to see Itinerary related classes in a class diagram. These are essential classes in this process.

josh-willis-arcadis · 2026-04-20T19:25:46Z

+("Unable to monitor trip") is sent.
+
+A provision exists in the `CheckMonitorTrip` logic, so that a notification that a trip is no longer possible is sent
+if no matching itinerary has been found for over a week. (This is not currently implemented.)


could be a good use of a note.

Updated in da5dbc0

josh-willis-arcadis · 2026-04-20T19:27:25Z

+Once an occurrence of a trip completes, the journey state is "reset",
+so that notifications can be sent again for the next trip occurrence.
+
+A `JourneyState` consists of the following attributes:


good place for another class diagram.

josh-willis-arcadis · 2026-04-20T19:32:16Z

+Upon saving a trip (POST), if the trip is recurring, OTP-middleware will perform an additional existence check.
+If the check does not succeed, the request is rejected, and the trip is not saved or monitored. If the check passes,
+the result is saved in `MonitoredTrip.itineraryExistence`.
+(The check is not performed when saving one-time trips.)


another good use of a note.

Updated in da5dbc0

josh-willis-arcadis · 2026-04-20T19:33:11Z

+
+| Notification Type | Description |
+| --- | --- |
+| `INITIAL_REMINDER` | Advance trip reminder ("Reminder for My Trip at 8:30"). If `MonitoredTrip.notifyAtLeadingInterval` is true, sent once at the lead monitoring time on the day a given trip occurs. |


this is a good method to include in class diagram.

Added notification methods in 193e507.

binh-dam-ibigroup added 30 commits March 20, 2026 16:26

docs(trip-monitoring): First draft.

3c1a37b

docs(trip-monitoring): Tweak notification text.

8d59624

Merge branch 'dev' into monitor-trip-docs

4e41a53

docs(trip-monitoring): Add trip monitoring lifecycle.

1941308

docs(trip-monitoring): Tweak sentences.

6eb2681

docs(trip-monitoring): Tweak notification section.

6593c13

docs(trip-monitoring): Add leg id diagrams.

65eafc1

docs(trip-monitoring): Improve leg id matching diagrams.

74b740b

docs(trip-monitoring): Improve leg id matching text.

1287f92

docs(trip-monitoring): Add config params.

fb5d3cc

docs(trip-monitoring): Add section on itin matching attempts.

a77f334

docs(live-tracking): Improve companion/observer notifications.

34800f9

docs(trip-monitoring): Improve trip notification types.

b61fe8a

docs(trip-monitoring): Improve trip notification section.

bf70d18

docs(README): Add link to trip monitoring.

7994a5d

docs(trip-monitoring): Group OTP configs together.

a5652a6

docs(trip-monitoring): Tweak notification types.

db868cb

docs(trip-monitoring): Start class schema.

7c00d5d

docs(trip-monitoring): Improve itin checking section.

22f0216

docs(trip-monitoring): Add section about one-time vs recurring trips.

dd518bb

docs(trip-monitoring): Add paragraph about trip no longer possible.

18eadb3

docs(trip-monitoring): Improve delay alerts.

cf2bf2a

docs(trip-monitoring): Fix classes handling itinerary matching.

5586e29

docs(trip-monitoring): Add JourneyState class.

6df3225

docs(trip-monitoring): Tweak intro wording and diagrams.

593cc54

docs(trip-monitoring): Try link to one class [skip ci]

c132f6c

docs(trip-monitoring): Improve itin matching text [skip ci]

028073f

docs(trip-monitoring): Tweak more text [skip ci]

9ab8264

docs(trip-monitoring): Improve journey state section [skip ci]

cd5dd0a

docs(trip-monitoring): Add paragraph about trip locking [skip ci]

b570ea3

binh-dam-ibigroup added 2 commits April 13, 2026 16:00

docs(trip-monitoring): Improve CheckMonitorTrip section [skip ci]

63eadd1

docs(trip-monitoring): Add class links and fix typos

142c325

binh-dam-ibigroup requested a review from br648 April 13, 2026 20:57

binh-dam-ibigroup assigned br648 Apr 13, 2026

br648 approved these changes Apr 14, 2026

View reviewed changes

br648 assigned binh-dam-ibigroup and unassigned br648 Apr 14, 2026

binh-dam-ibigroup added 2 commits April 15, 2026 10:16

docs(trip-monitoring): Add more info about leg id method

6f5e651

docs(trip-monitoring):

658e206

Improve section on slacks

binh-dam-ibigroup requested a review from josh-willis-arcadis April 15, 2026 15:58

binh-dam-ibigroup assigned josh-willis-arcadis and unassigned binh-dam-ibigroup Apr 15, 2026

alec-georgoff approved these changes Apr 15, 2026

View reviewed changes

binh-dam-ibigroup added 2 commits April 16, 2026 09:17

docs(trip-monitoring):

dd4ac78

Add notes sections

docs(trip-monitoring):

b71c5e6

Fix notes sections

josh-willis-arcadis approved these changes Apr 20, 2026

View reviewed changes

josh-willis-arcadis assigned binh-dam-ibigroup and unassigned josh-willis-arcadis Apr 20, 2026

binh-dam-ibigroup added 6 commits April 23, 2026 12:00

docs(trip-monitoring): Add trip mon methods.

58a6c3c

docs(trip-monitoring): Add trip notification methods.

193e507

docs(trip-monitoring): Add notes and run() meth in flow diagram.

da5dbc0

docs(trip-monitoring): Add itinerary existence-related methods.

fe2b038

docs(trip-monitoring): Add Itinerary to class diagram.

b0c7032

docs(trip-monitoring): Add diagram for JourneyState update.

632115d

binh-dam-ibigroup merged commit 5aba8ad into dev Apr 27, 2026
2 of 4 checks passed

binh-dam-ibigroup deleted the monitor-trip-docs branch April 27, 2026 18:42


		#### Plan Method

		If the leg id method fails, a `plan` GraphQL query is sent to OTP to replan the entire trip for the target date, using


		#### Leg ID Method

		The [`ItineraryChecker`](../src/main/java/org/opentripplanner/middleware/itinerarymatching/ItineraryChecker.java) class

Conversation

binh-dam-ibigroup commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Description

Uh oh!

br648 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alec-georgoff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josh-willis-arcadis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

binh-dam-ibigroup commented Apr 13, 2026 •

edited

Loading