mileograph_flutter/README.md

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:

   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):

  flutter run
  

• Release build (example for Android):

  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.