Bus Route Trainer
Queensland Bus Driver Route Learning & Memory Trainer.
An independent, specialised training application engineered to help Queensland bus drivers quickly learn and retain unfamiliar bus routes, service variations, stop sequences, and depot driver knowledge.
Language & Locale Standard: This project adheres to Australian English (en-AU) across all user interfaces, terminology (e.g. timetables, depot, centre, specialised), and user-facing documentation. The interface is also available in Traditional Chinese (zh-TW).
For Drivers — Using the App
Do I need to install anything?
No. Bus Route Trainer is a website. There is no app to download from the App Store or Google Play. You only need a modern web browser (Safari, Chrome, Edge, or Firefox) and an internet connection.
It works on phones, tablets, and desktop computers.
Quick start on your phone
- Open your phone's browser and go to the site address your depot gave you.
- Tap Register to create an account.
- Choose a username.
- Email is optional, but if you leave it blank you will not be able to reset a forgotten password. We recommend adding it.
- Your password must meet the rules shown on screen (see Password requirements).
- Sign in.
- From All routes, tap a route, then tap Enrol on the direction/variant you need to learn.
- Tap Start practice and answer the questions.
- Come back daily — the home screen shows what is due for review.
Add it to your home screen (optional)
This makes the site open like an app, without the browser address bar.
- iPhone / iPad (Safari): tap the Share button → Add to Home Screen → Add.
- Android (Chrome): tap the ⋮ menu → Add to Home screen → Add.
Note: this creates a shortcut only. The app still requires an internet connection — offline support is not yet implemented (see Roadmap).
How practice works
Practice uses active recall with a spaced repetition system (SRS):
- You are shown a hint (for example, a stop name) and must type the answer from memory.
- Cards you get right come back less often; cards you get wrong come back sooner.
- The home screen shows your daily review queue, practice streak, accuracy, and a mastery trend.
Two question modes are used:
| Mode | What you are asked |
|---|
| Next stop | Given the current stop, name the stop that comes next |
| Station identification | Given a position in the route, name that stop |
Password requirements
| Rule | Requirement |
|---|
| Length | At least 8 characters (12 or more recommended) |
| Lowercase | At least one a-z |
| Uppercase | At least one A-Z |
| Special character | At least one of !@#$%^&*()_+-=[]{}|;:,.<>? |
| Digits | Optional |
| Common passwords | Blocked (e.g. Password!1) |
Forgot your password? Tap Forgot password? on the sign-in page. A reset link is emailed to you and is valid for 1 hour, single use. This only works if you registered an email address.
⚠️ Safety notice
Never use this app while driving. It is a study tool for use before or after your shift.
Timetables, route alignments, and stop sequences come from periodic snapshots of open data and may be out of date. During actual operation, always follow official Translink depot notices, master run sheets, and radio dispatch instructions. See DISCLAIMER.md.
For Developers
Software you need to install
| Software | Why | Notes |
|---|
| Docker Desktop | Runs the app and PostgreSQL in containers | Required. macOS/Windows/Linux. After install, ensure docker is on your PATH (on macOS it may be at ~/.docker/bin) |
| Git | Clone the repository | Pre-installed on macOS/Linux; Windows users install Git for Windows |
That is all. Node.js and PostgreSQL are not installed on your machine — they run inside the container. This keeps every environment identical.
Project rule: never run node / npm directly on the host. The database only exists inside Docker, so host runs will fail or behave inconsistently. See AGENTS.md.
Optional: an editor with Dev Containers support (VS Code, Cursor, or Antigravity) lets you use Reopen in Container for a fully configured shell.
Setup SOP
# 1. Clone
git clone https://github.com/Jake627520/bus-route-trainer.git
cd bus-route-trainer
# 2. Create your local environment file
cp .env.example .env
Then edit .env. For local development, point both database URLs at the container's database and set an auth secret:
DATABASE_URL="postgresql://postgres:postgres@db:5432/bus_route_trainer"
DIRECT_URL="postgresql://postgres:postgres@db:5432/bus_route_trainer"
AUTH_SECRET="<output of: openssl rand -base64 32>"
# 3. Start the database
docker compose up -d db
# 4. Apply the schema
docker compose run --rm app npx prisma migrate deploy
# 5. Start the dev server
docker compose run --rm --service-ports app npm run dev -- -H 0.0.0.0
Open http://localhost:3000, register an account, and you are in.
The route list is empty until you import GTFS data — see Importing transport data.
Everyday commands
| Task | Command |
|---|
| Run tests | docker compose run --rm app npm test |
| Lint | docker compose run --rm app npx eslint . |
| Production build | docker compose run --rm app npx next build |
| Regenerate Prisma client | docker compose run --rm app npx prisma generate |
| Stop everything | docker compose down |
| Stop and wipe the database | docker compose down -v |
Tests run serially (--fileParallelism=false) because integration tests share one database.
Importing transport data
Download a GTFS feed from Translink Open Data, unzip it, then:
# Buses only (recommended first import)
docker compose run --rm app npx tsx scripts/import-gtfs.ts ./path-to-gtfs --bus-only
# Other modes, with a cap on how many routes are imported
docker compose run --rm app npx tsx scripts/import-gtfs.ts ./path-to-gtfs --route-types=2,4 --max-routes=50
| Flag | Effect |
|---|
--bus-only | Import bus routes only (GTFS route type 3) |
--route-types=2,4 | Import specific GTFS route types (2 = train, 3 = bus, 4 = ferry) |
--max-routes=N | Cap the number of routes — useful to stay inside a free database tier |
--clear | Delete existing GTFS tables before importing |
A scheduled GitHub Actions workflow refreshes the feed automatically; see .github/workflows/gtfs-update.yml.
Troubleshooting
| Symptom | Cause / fix |
|---|
Cannot connect to the Docker daemon | Docker Desktop is not running — start it |
Port 3000 is in use | An old dev container is still up: docker ps then docker rm -f <id> |
Unknown argument from Prisma | Stale generated client — run npx prisma generate inside the container |
Build fails on migrate | DIRECT_URL is missing or pointed at a pooled connection; migrations need a direct connection |
Redirected to /login in a loop | Cookies need HTTPS in production (SameSite=Lax + Secure) |
Architecture & workflow
- Stack: Next.js 16 (App Router) · React 19 · TypeScript · Prisma 6 · PostgreSQL · Tailwind CSS v4 · Vitest
- Method: OpenSpec (spec-first) + TDD. Changes are specified in
openspec/changes/<id>/ and reviewed before coding; tests go red before implementation turns them green.
- Data boundaries: official GTFS data, application data, and driver personal knowledge are kept in separate bounded contexts.
- Deployment:
DEPLOY.md · Handover notes: HANDOFF.md · Agent rules: AGENTS.md
Features
Available now
- Route & variant discovery — browse routes and enrol in specific directions/variants
- Active recall practice — next-stop and station-identification questions
- Spaced repetition (SRS) — adaptive review intervals driven by recall performance
- Review dashboard — daily review queue, practice streak, accuracy, and mastery trend
- Accounts — registration, sign-in, enforced password strength policy, and email password reset
- Bilingual interface — Australian English and Traditional Chinese
- Multi-mode data — bus, train, and ferry imports, with scheduled GTFS refresh
Roadmap
- Offline PWA support — not yet implemented; an internet connection is currently required
- Driver knowledge layer — personal notes, hazards, and depot pointers (data model exists; UI pending)
- Timetable & timing-point drills
- Multi-factor authentication (MFA)
Licensing, Copyright & Intellectual Property
This project keeps three things legally separate: the code, the transport data, and third-party branding.
1. Application source code — MIT
Copyright © 2026 Jake627520. Licensed under the MIT Licence — see LICENSE.
You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the code, provided the copyright notice and permission notice are retained. The software is provided "as is", without warranty of any kind.
2. Public transport data — CC BY 4.0 (separate licence)
Route, stop, trip, and timetable data is sourced from Translink Queensland Open Data, provided by the Department of Transport and Main Roads (Translink), Queensland Government, under Creative Commons Attribution 4.0 International (CC BY 4.0).
Important: the MIT licence covers the code only. It grants you no rights over the transport data. If you redistribute that data you must comply with CC BY 4.0 independently, including correct attribution to Translink.
Full details: DATA-LICENSE.md.
3. Trade marks & branding — not licensed
Translink, the Queensland Government, and the Department of Transport and Main Roads own their respective trade marks, logos, and visual identity. Those marks are deliberately not used in this application, and no licence to use them is granted or implied by the MIT licence.
Route numbers and stop names are factual identifiers used descriptively for training purposes; this does not imply endorsement.
4. Non-affiliation
This is an independent community project. It is not affiliated with, endorsed by, sponsored by, maintained by, or operated by Translink, the Department of Transport and Main Roads, or the Queensland Government.
5. No warranty & operational disclaimer
Provided "as is" with no warranty. Transport data is a periodic snapshot and may be inaccurate or outdated. Drivers must always follow official depot notices, master run sheets, and radio dispatch instructions during actual operation. Nothing here is operational advice.
Full text: DISCLAIMER.md.
6. Your data
Accounts store a username, an optional email address, and a salted password hash — passwords are never stored in plain text. Practice history is tied to your account and used to schedule your reviews. Self-hosters are responsible for their own privacy obligations.
Contributing
Contributions are accepted under the MIT Licence. By submitting a pull request you agree your contribution is licensed under the same terms, and you confirm you have the right to submit it. Follow the OpenSpec + TDD workflow described in AGENTS.md.
