69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# 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.
|