# Mileograph (Flutter)

Mileograph is a Flutter client for logging and analysing railway journeys. It lets you record legs, group them into trips, track locomotive mileage, and view stats and leaderboards.

## Features
- Add and edit journey legs with traction, timings, routes, notes, and delays.
- Group legs into trips and see mileage totals and traction stats.
- Browse traction, view loco details, mileage leaderboards, timelines, and legs.
- Dashboard with homepage stats, “On This Day”, recent traction changes, and trips.
- Profile badges, class clearance progress, and traction progress.
- Offline-friendly UI built with Provider, GoRouter, and Material 3 styling.

## Project layout
- `lib/objects/objects.dart` — shared model classes and helpers.
- `lib/services/` — API, data loading, auth, endpoints, distance units.
- `lib/components/` — UI pages and widgets (entries, traction, dashboard, trips, settings, etc.).
- `assets/` — icons/fonts and other bundled assets.

## Prerequisites
- Flutter SDK (3.x or later recommended).
- Dart SDK (bundled with Flutter).
- A Mileograph API endpoint (set in Settings within the app).

## Setup
1) Install Flutter: follow https://docs.flutter.dev/get-started/install and ensure `flutter doctor` is green.  
2) Get dependencies:  
   ```bash
   flutter pub get
   ```
3) Configure an API endpoint:
   - Run the app, open Settings, and set the base URL for your Mileograph backend.
   - The app probes the endpoint for a version string before saving.

## Running
- Debug (mobile/web depending on your toolchain):  
  ```bash
  flutter run
  ```
- Release build (example for Android):  
  ```bash
  flutter build apk --release
  ```

## Testing and linting
- Static analysis: `flutter analyze`
- Unit/widget tests (if present): `flutter test`

## Contributing
1) Fork or branch from `main`.  
2) Make changes with clear, small commits.  
3) Add tests where feasible and keep `flutter analyze` clean.  
4) Submit a PR describing:
   - What changed and why.
   - How to test or reproduce.
   - Any API or migration notes.

### Coding conventions
- Prefer stateless widgets where possible; keep state localized.
- Use existing services in `lib/services` for API access; add new endpoints there.
- Keep models in `objects.dart` (or nearby files) and use helper parsers for defensive JSON handling.
- Follow Material theming already in use; keep strings user-facing and concise.

### Issue reporting
Include device/OS, Flutter version (`flutter --version`), steps to reproduce, expected vs. actual behaviour, and logs if available.

## License
Copyright © Mileograph contributors. See repository terms if provided.