trilliumlab/forest-park-reports-app

# Trail Eyes App

A hazard-tracking app for Forest Park, Portland. Development sponsored by Portland State University and NSF award CIF-2046175. [![Release][release-shield]][release-url] [![Build Status][actions-shield]][actions-url] [![Last Commit][last-commit-shield]][last-commit-url] [![License][license-shield]][license-url]

Downloads

Nightly builds are available through CI from the actions tab. App Store/Play Store builds are not available yet.

The latest nightly builds can be found here:

[!WARNING]
Nightly builds are experimental and untested. Builds are distributing for testing purposes only, and may not be stable.

About

Trail Eyes is developed in Flutter. For more information, see the online documentation.

How to Build

Required

Flutter >= 3.0.0
Xcode (optional; only required for iOS/MacOS builds)

Installation

Clone this project:

git clone https://github.com/trilliumlab/forest-park-reports-app.git

Most work happens on the dev branch. To switch to the dev branch:
```
git checkout dev
```
Fetch project dependencies:
```
flutter pub get
```
Create a .env file in the project root. This step is required, but adding a mapbox api key is optional.
```
MAPBOX_KEY=API_KEY_HERE
```

Running

Run code generation:
```
dart run build_runner build
```

[!IMPORTANT]
Code generation needs to be run whenever files in lib/model and lib/provider are modified. To have code generation automatically run on save, run dart run build_runner watch

Now your can run Trail Eyes:
```
flutter run
```

[!NOTE]
iOS development requires some extra setup. To configure a signing certificate, open ios/Runner.xcworkspace in Xcode. Ensure you're signed into your development Apple ID, and select Runner in the sidebar. Under Signing & Capabilities, select Automatically manage signing, and select your team under the Team dropdown.

Building

To build an APK for android:
```
flutter build --release apk
```
To build an IPA for iOS:
```
flutter build --release ipa
```

[!NOTE]
The export options must be configured in Xcode manually after the first run. Open build/ios/archive/Runner.xcarchive in Xcode and distribute the IPA. This will produce an ExportOptions.plist that can be used to automatically build IPAs with the same settings in the future. To pass the ExportOptions.plist to flutter, append --export-options-plist=path/to/ExportOptions.plist to the previous command.

Project Structure

forest-park-reports-app
├── android # native Android project
├── assets # app assets
│   ├── icon # Trail Eyes icon
│   └── markers # trail start/end marker
├── ios # native iOS project
├── lib # flutter code src directory
│   ├── model # data models - uses freezed and json_serializable for codegen
│   ├── page # holds pages and widgets
│   │   ├── common # widgets reusable across all pages
│   │   ├── home_page # widgets specific to home_page
│   │   │   ├── map_page # widgets specific to map_page
│   │   │   └── panel_page # widgets specific to panel_page
│   │   └── settings_page # widgets specific to settings_page
│   ├── provider # riverpod providers - all state management should be here
│   └── util # utility/extension functions
├── linux # native Linux project
├── macos # native MacOS project
├── web # native web project
└── windows # native Windows projecct

Assets

The assets/icon folder contains the app icon. This was created in Adobe Illustrator and the source files are [icon 3d.ai](assets/icon/icon 3d.ai) for the main icon and icon.ai for a flat version. icon.png is the full rendered icon, and background.png and foreground.png are separated bg/fg layers (used by android adaptive icons).

Custom icon symbols go in the assets/icons directory (svgs only). The icons are loaded in flutter using a font file. To generate the font file and the dart icon class, run:

dart run icon_font_generator:generator

Contributing

Contributions are welcomed! If you have any suggestions, feel free to open a pull request.

Fork the project.
Create a new branch git checkout -b feature/new-feature-name
Commit your changes git commit -m 'Added new feature
Push your changes git push
Open a pull request.

Not up for a pull request? Feel free to open an issue.

License

Trail Eyes is provided under the MIT license. See LICENSE.md