Bus Running Record (BRR) App

A Flutter mobile app for rail replacement controllers to generate and fill Bus Running Reports (BRRs) from schedule documents. Eliminates manual data entry by parsing schedule files and providing a streamlined interface for completing required fields.

Features

Implemented (MVP)

• Schedule Upload & Parsing

  • Upload .docx schedule documents
  • Parse Arriva schedule format to extract trip data
  • Extract trip numbers, duty numbers, running numbers, fleet numbers, and scheduled times
  • Error handling for invalid/unparseable files

• Trip List View

  • Display all parsed trips in scrollable list
  • Show pre-filled data from schedule
  • Expandable trip cards for detailed view
  • Real-time completion status tracking

• Data Entry Interface

  • Quick entry for actual departure time and fleet number
  • "Same as scheduled" and "As planned" buttons for quick filling
  • Auto-save functionality using local storage
  • Input validation

• BRR Export

  • Generate Excel (.xlsx) files in BRR template format
  • Include all trip data (scheduled and actual)
  • Preserve BRR template formatting
  • Share functionality via system share sheet

Architecture

Project Structure

lib/
├── main.dart                    # App entry point with routing
├── models/                      # Data models
│   ├── trip.dart               # Trip data model
│   ├── brr_metadata.dart       # BRR metadata model
│   └── brr_state.dart          # App state model
├── parsers/                     # Schedule parsers
│   ├── schedule_parser.dart    # Parser interface
│   └── arriva_schedule_parser.dart  # Arriva format parser
├── exporters/                   # Excel exporters
│   ├── brr_exporter.dart       # Exporter interface
│   └── arriva_brr_exporter.dart # Arriva BRR exporter
├── services/                    # Business logic services
│   ├── brr_export_service.dart # Export service with validation
│   └── storage_service.dart    # Local storage service
├── validators/                  # Data validators
│   └── trip_validator.dart     # Trip data validator
├── pages/                       # UI screens
│   ├── home_page.dart          # Upload screen
│   └── trip_list_page.dart     # Trip list and editing screen
└── exceptions/                  # Custom exceptions
    └── schedule_parse_exception.dart

Key Components

Parsers

• ArrivaScheduleParser: Parses Arriva .docx schedules using regex patterns
  • Handles regular trips and finishing trips
  • Extracts all required fields from trip lines
  • Time formatting (HHMM → HH:MM)

Exporters

• ArrivaBRRExporter: Generates Excel files in BRR format
  • Creates proper header structure
  • Populates trip data
  • Applies cell formatting and column widths
  • Saves to device storage

Services

• BRRExportService: Validates and exports BRRs
  • Pre-export validation
  • Error handling and reporting
• StorageService: Auto-save using SharedPreferences
  • Persists trip data locally
  • Restores state on app restart

Dependencies

• flutter: Flutter framework
• go_router: Navigation and routing
• file_picker: Document file selection
• docx_to_text: Parse .docx files
• excel: Generate Excel files
• share_plus: Share files via system share sheet
• path_provider: File system access
• shared_preferences: Local data persistence

Getting Started

Prerequisites

• Flutter SDK 3.10.0 or higher
• Dart SDK 2.18 or higher
• Android Studio / Xcode for platform-specific builds

Installation

1. Clone the repository
2. Install dependencies:

   flutter pub get
   

3. Run the app:

   flutter run
   

Building for Release

Android:

flutter build apk --release

iOS:

flutter build ios --release

Usage

1. Upload Schedule

   • Tap "Upload Schedule (.docx)" on home screen
   • Select an Arriva schedule .docx file
   • App will parse and display trip count

2. Fill Trip Data

   • View list of all parsed trips
   • Tap a trip card to expand
   • Enter actual departure time and fleet number
   • Use quick-fill buttons for common cases
   • Data auto-saves as you work

3. Export BRR

   • Tap "Export BRR" when all trips are complete
   • Excel file is generated and saved
   • Option to share via email, messaging, etc.

MVP Scope

This is the MVP (Minimum Viable Product) version focused on:

• Arriva schedule format only
• Basic validation
• Local storage only
• No cloud sync
• No user authentication

Future Enhancements

• Support for multiple TOC formats (First, Stagecoach, National Express)
• Multi-route support in single session
• Historical BRR archive
• Analytics and reports
• Real-time collaboration
• Cloud sync
• Photo upload with OCR
• Integration with radio/messaging systems

Testing

The app has been developed according to the MVP specification in MVP.md.

Test Scenarios

1. Upload valid Arriva schedule → correct trip parsing
2. Parse trips → all fields populated correctly
3. Enter actual times/fleet → data saved
4. Export BRR → valid Excel file generated
5. Re-open app → previous data persisted

Contributing

This is a private project developed for rail replacement controllers.

License

Private - All rights reserved

Credits

Developed according to specifications in MVP.md