# 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:
   ```bash
   flutter pub get
   ```
3. Run the app:
   ```bash
   flutter run
   ```

### Building for Release

**Android:**
```bash
flutter build apk --release
```

**iOS:**
```bash
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`