Keystone Transit Tracking
Design Spec & Logic
Last updated: 21 August 2026
Reach Design System
A read-only record of every rule and behaviour agreed for the transit board, and the reasoning behind each one. Sections describe only what is actually built today — anything still aspirational lives on the Lifecycle Board, not here.
1
Purpose & scope
A single live board for boarding staff to see where every student is right now, and to move students between the boarding house and campus locations.
- Rebuilt from the original Keystone tracking prototype into the Reach Design System.
- Audience is house parents and boarding staff on a desktop or kiosk screen.
- Scope is present-tense movement only: not leave approval, not rollcall, not pastoral notes.
- Every count on the page derives from one student list — no separately maintained totals.
2
Data model
One flat student list and one location list drive the entire board.
Student record
- name, cardId (RFID value the scanner field matches), floor (boarding-house floor).
- locationId — the location the student is at or heading to.
- arrived — boolean. False means in transit to locationId.
- since — timestamp of the last movement, driving all elapsed-time and late calculations.
- originId — where an inbound student departed from, so returns can be grouped by location.
Locations
- One home location (Boarding House) plus four destinations: Gymnasium 90, Music Room 60, Fitness Centre 50, Library 120.
- Only destinations carry a capacity. Home base has none.
- Each destination owns an identity colour used consistently across the board.
Location configuration — System Configuration → In Transit
The tracking screen is configured from the In Transit page in Reach System Configuration, by naming which locations belong to each group. The right-hand Locations column of the board is the destination locations.
- 5910 — To Transit Locations — which locations represent travel away from the home base. Their Default Leave sets the permitted transit time out.
- 5911 — From Transit Locations — which locations represent travel back to the home base. Their Default Leave sets the permitted transit time home.
- Destination locations — the places students are tracked at, shown as the Locations column. Their Default Leave sets how long a student may stay before counting as late to depart, and their capacity caps occupancy.
- Home base location — the single base every journey starts and ends at, shown as the left column. One location, not a set.
- Home base sub-element — a Reach Lookup selected as the breakdown listed inside the home base. With Boarding House as home base and Lookup = Floor, the tiles read East 2, East 3 and so on. Choosing a different Lookup changes the breakdown without any other change to the board.
Not yet implemented
All five settings above are defined in code, not through a configuration screen. Naming the three location groups, choosing the home base and its Reach Lookup sub-element, and setting Default Leave and capacity per location, are all on the Lifecycle Board.
Note — sample data
300 students are generated from a fixed name list with a spread of elapsed times, so the board opens with realistic on-time, late and overdue cases. State persists in the browser under one key. There is no back end.
3
Board layout
Three columns left to right, mirroring the direction of travel: where students live, who is moving, where they are going.
- Home base — one green panel with the in-house count and floor breakdown.
- In transit — two amber dashed panels: to locations, and from locations.
- Locations — one white card per destination, top-bordered in that location's colour.
- The Reach global top bar sits above the page; the page header carries a live ticking clock and today's date.
- Expand all / Collapse all act on every panel at once; otherwise each panel is independent.
- A hamburger in the top bar opens the left drawer holding the product screen and these two documentation pages.
4
Arrival model — transit vs signed in
The central rule of the board. Being sent somewhere and being counted there are two separate events.
- Assigning a student to a location starts a transit: arrived becomes false and the clock resets.
- In-transit students appear in that location's expanded list but do not increase its count.
- Only an explicit Sign in flips arrived to true and adds the student to the count.
- Capacity is checked at sign-in, not at assignment — a full room never blocks a student being sent.
- An in-transit student can be redirected to a different location without ever signing in.
- Returning to the boarding house works identically: in transit first, then signed in.
Why
A count that includes students still walking across campus is not a headcount. Staff need the number physically present, with pending arrivals visible but separate.
5
Home base & floors
- Headline count is students signed in at the boarding house.
- Ten floor tiles (East 2–5, West 2–7) each show their own signed-in count. The tiles come from the Reach Lookup chosen as the home base sub-element.
- Clicking a floor tile opens Find a student filtered to that floor.
- Expanding the panel lists every student in house with their time since arrival.
6
In-transit sections
Two panels, one per direction, each broken down by individual location rather than a single total.
Per-location rows
- One row per destination, read as To Gymnasium 2 | 4 — 2 on time, 4 late, 6 in transit.
- On-time count is amber, late is red; zero counts render muted.
- All locations always show, including zeros, so the set of rows never shifts.
- The panel header carries the section total as a pill.
- Outbound rows group by destination; inbound rows group by originId.
Drill-down
- Clicking a location row expands the panel filtered to that location, and highlights the row in its colour.
- The expanded list is headed by the active filter with a Show all locations link to widen back out.
- Opening the panel by its chevron shows all locations unfiltered; collapsing clears the filter.
- Late students sort above on-time students in the expanded list.
7
Locations & capacity
- Each card shows signed-in count over capacity, in the location's colour.
- At or over capacity the card border turns red and a FULL badge appears.
- Expanding a card lists in-transit students first, labelled in transit · Xm, then students present.
- In-transit entries turn red and gain a LATE marker past the permitted window.
- A full location still accepts inbound transits; the block happens at sign-in with a red toast.
8
Thresholds & overdue
- 15 minutes — permitted transit time. Past this a student counts as late in the on-time / late split.
- 60 minutes — overdue. Still in transit to a destination past this appears in the red banner at the top.
- The overdue banner states the count and expands into columns per destination.
- The banner hides itself entirely when nobody is overdue.
- Durations show as minutes under an hour, then 1h 20m style, refreshing every second.
Known simplification
Both thresholds are single global constants. They are not per-location, per-time-of-day or per-year-group, and they are not editable from the interface.
9
Find a student
One panel serves scanning, typing and browsing, because a kiosk needs all three.
- Opened from the search button in the page header; the field autofocuses so a scanner works immediately.
- An exact card-ID match opens that student's SISO panel straight away.
- A name search narrowing to exactly one student also opens it automatically.
- A vertical selector down the right side offers combined letter pairs — A-B through Y-Z — matching on first name.
- Pairs with no matching students are dimmed and inert.
- Result rows show the silhouette avatar, name, and current location or in-transit destination.
- Clicking the overlay outside the panel closes it.
10
SISO panel actions
- Opens from any student chip or search result, with a navy header matching the Reach modal pattern.
- Shows avatar, name, elapsed time, and current location as a coloured pill.
- For an in-transit student: an amber block explaining they are not yet counted, plus Sign in at [Location].
- From the boarding house the list covers all four destinations, labelled Assign to when present and Redirect to when in transit.
- From a campus location the only target is the boarding house, labelled Depart to — destination-to-destination moves are not offered.
- A student in transit is offered exactly two actions: sign in at the destination they were heading to, or Or return to the location they departed from. No other locations appear.
- Every movement records the departure location, so the return option is always the place they actually came from.
- Every action confirms with a toast — green for success, red for a capacity block — and returns to Find a student for the next scan.
11
Activity log
- Sits below the board; newest entry first, capped at the last 40 movements.
- Each line is timestamped to the second: student, from, to.
- Starting a transit and signing in are logged as separate entries, so both halves of a movement are visible.
- The empty state explains how entries appear rather than showing a blank panel.
Known simplification
The log is a rolling 40-entry window held with board state. Movements beyond that are discarded, so no historical reporting is possible from it yet.
12
Visual system
- Reach Design System throughout the product screen: Roboto, navy chrome, teal as the interactive accent, flat surfaces, no gradients.
- Reach components in use: AppTopBar, StatusAvatar, Button, Icon.
- Status colour meaning is fixed — green present or home, amber in transit or pending, red late or full.
- Each destination carries its own identity colour, used consistently on its card, rows and avatar rings.
- Counts use tabular figures so digits do not jitter as the clock ticks.
- These two documentation pages use the tracker's own fixed governance palette, not the product palette, so they look identical across projects.
Substitution
Student photos are a neutral silhouette placeholder. The status ring carries the meaning, so real photography can drop in without any other change. No school crest was supplied, so the top bar shows the default Reach brand mark.
Open questions — raised, not yet resolved
- Should the 15 and 60 minute thresholds vary by location or time of day, and who edits them?
- Does an overdue student trigger anything beyond the banner — a notification to the house parent on duty?
- Should students be able to sign themselves in at a location kiosk, or is this staff-only?
- Do transits need an expected return time, so the board can distinguish late back from late arriving?
- Should a redirect be recorded as a distinct event type in the log rather than a new transit?
- Is a full location ever hard-blocked, or is the sign-in warning always overridable by staff?
- What happens to in-transit students at end of day — automatic reconciliation, or a manual sweep?
- Does the board need a mobile layout for staff walking campus?
- How long should movement history be retained once the 40-entry log is replaced by real storage?
- Where does duty state live, so Alert Profiles can read a staff member's real-time On Duty status at the moment an alert triggers?
- If nobody in the Boarding Supervisor role is On Duty when an alert fires, who receives it instead?