Some changes to make the project ready to merge to main
- Fix formatting.
- Add project to the `stable` channel CI (potentially could be added for
`beta` and `master`)
- CI only runs when targeting `main`, so I run the command locally and
it worked.
- Add unit tests for the `ApiClient` and `AuthApiClient` which had no
test coverage outside of integration tests.
- Resolved some TODOs I left before.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR removes the `compass_model` subproject and moves each data model
class to the respective `app` or `server` project.
Although this leads to code duplication, this is a more realistic
implementation where clients and servers have their own respective data
model class implementations.
The model classes for the server are located in `server/lib/model`.
Model classes for the app are located in two places:
- API-only model: `app/lib/data/services/api/model`.
- Domain model: `app/lib/domain/model`.
In general, models located under the domain are used across the app,
while the API-only models are only used for interacting with the API
client.
Tests have been updated.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR introduces the storage and retrieval of bookings.
### Server implementation
- New booking routes:
- GET `/booking`: Obtain the list ofer user bookings
- GET `/booking/{id}`: Obtain the specific booking object
- POST `/booking`: Creates a new booking
- The `BookingApiModel` objects are incomplete, the `Destination` is a
reference, not the full object, and the `Activity` list are also listed
as references only.
- Server booking always has an existing booking created (Alaska, North
America) for demo purposes.
- Storage is "in memory", stopping the server deletes all stored
bookings.
### New `BookingRepository`
- New repository class.
- Both local and remote implementations.
- Converts the `BookingApiModel` into a complete `Booking` that the app
can use, or a `BookingSummary` that only contains the necessary
information for the home screen.
### New `LocalDataService`
- Service that loads hard-coded data or from assets.
### New `HomeScreen`
- Route path: `/`
- Loads and displays the list of created bookings from the
`BookingRepository`.
- Tap on a booking title opens the `BookingScreen`.
- Floating Action Button to create a new booking.
### Changes in `BookingScreen`
- Can be accessed at the end of creating a booking or from the home
screen when tapping a booking title.
- Two commands:
- `createBooking`: Takes the stored `ItineraryConfig` and creates a
booking, the booking is stored to the `BookingRepository` (locally or on
the server).
- `loadBooking`: Takes a booking ID and loads that existing booking from
the `BookingRepository`.
- Simplified navigation: Once at `BookingScreen`, user can only navigate
back to `HomeScreen`.
- Share button converted to `FloatingActionButton`
### Integration Tests
- Updated to use new home screen.
- Updated to cover opening an existing booking in tests.
### TODO Next
- Refactor the `compass_model` project and move data model classes to
`server` and `app`, then delete project.
- Implement some user information for the home screen (e.g. retrieve
user name and profile picture url)
### Screencast
[Screencast from 2024-09-02
16-25-25.webm](https://github.com/user-attachments/assets/8aba4a61-def6-4752-a4e5-70cbed362524)
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR follows up with the conversation we had via email and cleans up
the auth implementation.
**New `AuthRepository`**
The `AuthTokenRepository`, `AuthLoginComponent` and
`AuthLogoutComponent` have been refactored into a single
`AuthRepository`.
This `AuthRepository` exposes the `isAuthenticated` boolean, which is
used by `go_router` to handle redirects.
Also, has two methods, `login(email, pass)` and `logout()`, similar to
what we had in the components.
The implementation uses the new `SharedPreferencesService`, which is a
service to access the `shared_preferences` plugin to store the `String`
token.
**New `AuthApiClient`**
The `ApiClient` has been split in two. The `/login` REST call is moved
to the `AuthApiClient`, while the other calls that require an auth token
remain in the `ApiClient`.
**`ApiClient` credentials**
The main open question is, what is the best way to pass the auth token
to the api client?
I've found several alternatives:
1. `ApiClient` has a `token` setter which the `AuthRepository` calls to
set the token
- Implemented in this PR.
- Follows our architecture design.
- `AuthRepository` should be the source of truth, but the
`ApiClient.token` could be set externally by mistake, so the single
source of truth principle gets blurry.
2. `ApiClient` calls to the `AuthRepository` to obtain the token.
- This is what the code was doing before.
- `AuthRepository` is the source of truth.
- But the dependency "Service to Repository" breaks our architecture
design principle.
3. `ApiClient` calls to the `SharedPreferencesService` to obtain the
token (
- `SharedPreferencesService` is the source of truth, as the `ApiClient`
doesn't need the `AuthRepository`.
- We see a "Service calling a Service" which maybe breaks our
architecture design principle?
4. The `ApiClient` doesn't hold the token at all, intead, each call
requires us to pass a token.
- Tried to implement it but becomes very complex.
- Makes other repositories depend on the `AuthRepository` or the
`SharedPreferencesService`.
Personal take: I have implemented 1 in this PR because it is the one
that follows best the architecture recommendations. However I see some
pitfalls, e.g. the `AuthRepository` needs to fetch the token from the
`SharedPreferencesService` at least once on app start and pass it to the
`ApiClient`. While on the solution 2 that's never a problem, since the
`AuthRepository` is being called from the `ApiClient` and so it is
always the source of truth for authentication.
I am looking forward for your thoughts @ericwindmill
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR goes on top of PR #2385 adding integration test using the
`integration_test` package.
Adds `integration_test` folder with two test suits:
- Local test: Uses the local dependency config that pulls data from the
assets folder and has no login logic.
- Remote test: Starts the dart server in the background and uses the
remote dependency config, pulls data from the server and performs
login/logout.
To run the tests:
```
flutter test integration_test/app_server_data_test.dart
```
or
```
flutter test integration_test/app_local_data_test.dart
```
Running both at once with `flutter test integration_test` will likely
fail, seems this issue is related:
https://github.com/flutter/flutter/issues/101031
Also, this PR fixes exceptions being thrown by the network image
library, now instead they get logged using the app `Logger`.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR introduces basic auth implementation between the app and the
server as part of the architectural example.
This PR is a big bigger than the previous ones so I hope this
explanation helps:
### Server implementation
The server introduces a new endpoint `/login` to perform login requests,
which accepts login requests defined in the `LoginRequest` data class,
with an email and password.
The login process "simulates" checking on the email and password and
responds with a "token" and user ID, defined by the `LoginResponse` data
class. This is a simple hard-coded check and in any way a guide on how
to implement authentication, just a way to demonstrate an architectural
example.
The server also implements a middleware in
`server/lib/middleware/auth.dart`. This checks that the requests between
the app and the server carry a valid authorization token in the headers,
responding with an unauthorized error otherwise.
### App implementation
The app introduces the following new parts:
- `AuthTokenRepository`: In charge of storing the auth token.
- `AuthLoginComponent`: In charge of performing login.
- `AuthLogoutComponent`: In charge of performing logout.
- `LoginScreen` with `LoginViewModel`: Displays the login screen.
- `LogoutButton` with `LogoutViewModel`: Displays a logout button.
The `AuthTokenRepository` acts as the source of truth to decide if the
user is logged in or not. If the repository contains a token, it means
the user is logged in, otherwise if the token is null, it means that the
user is logged out. This repository is also a `ChangeNotifier`, which
allows listening to change in it.
The `GoRouter` has been modified so it listens to changes in the
`AuthTokenRepository` using the `refreshListenable` property. It also
implements a `redirect`, so if the token is set to `null` in the
repository, the router will redirect users automatically to the login
screen. This follows the example found in
https://github.com/flutter/packages/blob/main/packages/go_router/example/lib/redirection.dart
On app start, `GoRouter` checks the `AuthTokenRepository`, if a token
exists the user stays in `/`, if not, the user is redirected to
`/login`.
The `ApiClient` has also been modified, so it reads the stored token
from the repository when performing network calls, and adds it to the
auth headers.
The two new components implement basic login and logout functionality.
The `AuthLoginComponent` will send the request using the `ApiClient`,
and then store the token from the response. The `AuthLogoutComponent`
clears the stored token from the repository, and as well clears any
existing itinerary configuration, effectively cleaning the app state.
Performing logout redirects the user to the login screen, as explained.
The `LoginScreen` uses the `AuthLoginComponent` internally, it displays
two text fields and a login button, plus the application logo on top. A
successful login redirects the user to `/`.
The `LogoutButton` replaces the home button at the `/`, and on tap it
will perform logout using the `AuthLogoutComponent`.
**Development target app**
The development target app works slightly different compared to the
staging build. In this case, the `AuthTokenRepository` always contains a
fake token, so the app believes it is always logged in.
Auth is only used in the staging build when the server is involved.
## Screenshots
<details>
<summary>Screenshots</summary>
The logout button in the top right corner:
The login screen:
</details>
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR adds the Booking screen at the end of the main app flow.
After the user selects `Activity`s, these get stored in the
`ItineraryConfig` and then the user navigates to the `BookingScreen`.
In the `BookingScreen`, a `Booking` is generated with the
`BookingCreateComponent`.
This component communicates with multiple repositories, and it is a bit
more complex than the average view model, something that we want to show
as discussed in the previous PRs.
<details>
<summary>Screenshots</summary>
</details>
In the `BookingScreen`, the user can tap on "share trip" which displays
the OS share sheet functionality. This uses the plugin `share_plus`, but
the functionality is also wrapped in the `BookingShareComponent`, which
takes a `Booking` object and creates a shareable string, then calls to
the `Share.share()` method from `share_plus`. But the `share_plus`
dependency is also injected into the `BookingShareComponent`, allowing
us to unit test without plugin dependencies.
This is an example of a shared booking to instant messaging:
**TODO**
- I want to take a look at the whole experience on mobile, as I noticed
some inconsistent UI and navigation issues that I couldn't see on
Desktop. I will submit those in a new PR.
- We also talked about user authentication in the design document. I
will work on that once we are happy with the main app flow.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR introduces the Activities screen, handling of errors in view
models and commands, and logs using the dart `logging` package.
**Activities**
- The screen loads a list of activities, split in daytime and evening
activities, and the user can select them.
- Server adds the endpoint `/destination/<id>/activitity` which was
missing before.
Screencast provided:
[Screencast from 2024-07-29
16-29-02.webm](https://github.com/user-attachments/assets/a56024d8-0a9c-49e7-8fd0-c895da15badc)
**Error handling**
_UI Error handling:_
In the screencast you can see a `SnackBar` appearing, since the
"Confirm" button is not yet implemented.
The `saveActivities` Command returns an error `Result.error()`, then the
error state is exposed by the Command and consumed by the listener in
the `ActivityScreen`, which displays a `SnackBar` and consumes the
state.
Functionality is similar to the one found in [UI events - Consuming
events can trigger state
updates](https://developer.android.com/topic/architecture/ui-layer/events#consuming-trigger-updates)
from the Android architecture guide, as the command state is "consumed"
and cleared.
The Snackbar also includes an action to "try again". Tapping on it calls
to the failed Command `execute()` so users can run the action again.
For example, here the `saveActivities` command failed, so `error` is
`true`. Then we call to `clearResult()` to remove the failed status, and
show a `SnackBar`, with the `SnackBarAction` that runs `saveActivities`
again when tapped.
```dart
if (widget.viewModel.saveActivities.error) {
widget.viewModel.saveActivities.clearResult();
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: const Text('Error while saving activities'),
action: SnackBarAction(
label: "Try again",
onPressed: widget.viewModel.saveActivities.execute,
),
),
);
}
```
Since commands expose `running`, `error` and `completed`, it is easy to
implement loading and error indicator widgets:
[Screencast from 2024-07-29
16-55-42.webm](https://github.com/user-attachments/assets/fb5772d0-7b9d-4ded-8fa2-9ce347f4d555)
As side node, we can easily simulate that state by adding these lines in
any of the repository implementations:
```dart
await Future.delayed(Durations.extralong1);
return Result.error(Exception('ERROR!'));
```
_In-code error handling:_
The project introduces the `logging` package.
In the entry point `main_development.dart` the log level is configured.
Then in code, a `Logger` is creaded in each View Model with the name of
the class. Then the log calls are used depending on the `Result`
response, some finer traces are also added.
By default, they are printed to the IDE debug console, for example:
```
[SearchFormViewModel] Continents (7) loaded
[SearchFormViewModel] ItineraryConfig loaded
[SearchFormViewModel] Selected continent: Asia
[SearchFormViewModel] Selected date range: 2024-07-30 00:00:00.000 - 2024-08-08 00:00:00.000
[SearchFormViewModel] Set guests number: 1
[SearchFormViewModel] ItineraryConfig saved
```
**Other changes**
- The json files containing destinations and activities are moved into
the `app/assets/` folders, and the server is querying those files
instead of their own copy. This is done to avoid file duplication but we
can make a copy of those assets files for the server if we decide to.
**TODO Next**
- I will implement the "book a trip" screen which would complete the
main application flow, which should introduce a more complex
"component/use case" outside a view model.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
Part of the WIP for the Compass App example. Merge to `compass-app`.
This PR introduces:
- A new feature for Activities (UI unfinished).
- A repository for the current Itinerary Configuration.
- A `Command` utils class to be used in View Models.
**Activities**
- PR adds the `compass_app/app/assets/activities.json` (large file!)
- Created `ActivityRepository` with local and remote implementation.
- Added `getActivitiesByDestination` to `ApiClient`
- Added `Activity` data model
- Created `ActivitiesScreen` and `ActivitiesViewModel`.
- WIP: Decided to finish the UI later due to the size the PR was taking.
- WIP: Server implementation for Activities will be completed in another
PR.
**Itinerary Configuration**
- Created the `ItineraryConfigRepository` with an "in-memory"
implementation. (local database or shared preferences could potentially
be implemented too)
- Refactored the way screens share data, instead of passing data using
the navigator query parameters, the screens store the state (the
itinerary configuration) in this repository, and load it when the screen
is opened.
- This allows to navigate between screens, back and forth, and keep the
selection of data the user made.
**Commands**
- To handle button taps and other running actions.
- Encapsulates an action, exposes the running state (to show progress
indicators), and ensures that the action cannot execute if it is already
running (to avoid multiple taps on buttons).
- Two implementations included, one without arguments `Command0`, and
one that supports a single argument `Command1`.
- Commands also provide an `onComplete` callback, in case the UI needs
to do something when the action finished running (e.g. navigate).
- Tests are included.
**TODO in further PRs**
- Finish the Activities UI and continue implementing the app flow.
- Introduce an error handling solution.
- Move the data jsons into a common folder (maybe a package?) so they
can be shared between app and server and don't duplicate files.
**Screencast**
As it can be observed, the state of the screen is recovered from the
stored "itinerary config".
Note: Activites screen appears empty, the list is just printed on
terminal at the moment.
[Screencast from 2024-07-23
10-58-40.webm](https://github.com/user-attachments/assets/54805c66-2938-48dd-8f63-a26b1e88eab6)
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
This PR introduces two new subprojects:
- `compass_server` under `compass_app/server`.
- `compass_model` under `compass_app/model`.
**`compass_server`**
- Dart server implemented using `shelf`.
- Created with the `dart create -t server-shelf` template.
- Implements two REST endpoints:
- `GET /continent`: Returns the list of `Continent` as JSON.
- `GET /destination`: Returns the list of `Destination` as JSON.
- Generated Docker files have been removed.
- Implemented tests.
- TODO: Implement some basic auth.
**`compass_model`**
- Dart package to share data model classes between the `server` and
`app`.
- Contains the data model classes (`Continent`, `Destination`).
- Generated JSON from/To methods and data classes using `freezed`.
- The sole purpose of this package is to host the data model. Other
shared code should go in a different package.
**Other changes**
- Created an API Client to connect to the local dart server.
- Created "remote" repositories, which also implement a basic in-memory
caching strategy.
- Created two dependency configurations, one with local repositories and
one with remote repos.
- Created two application main targets to select configuration:
- `lib/main_development.dart` which starts the app with the "local" data
configuration.
- `lib/main_staging.dart` which starts the app with the "remove" (local
dart server) configuration.
- `lib/main.dart` still works as default entry point.
- Implemented tests for remote repositories.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
Part of the implementation of the Compass App for the Architecture
sample.
**Merge to `compass-app`**
This PR introduces the Search Form Screen, in which users can select a
region, a date range and the number of guests.
The feature is split in 5 different widgets, each one depending on the
`SearchFormViewModel`. The architecture follows the same patterns
implemented in the previous PR
https://github.com/flutter/samples/pull/2342
TODO later on:
- Error handling is yet not implemented, we need to introduce a "logger"
and a way to handle error responses.
- All repositories return local data, next steps include creating the
dart server app.
- The search query at the moment only takes the "continent" and not the
dates and number of guests, that would be implemented later on as well.
## Demo
[Screencast from 2024-07-12
14-30-48.webm](https://github.com/user-attachments/assets/afbcdd4e-617a-49cc-894c-8e082748e572)
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
As part of the work for the compass-app / architecture examples
This PR is considerably large, so apologies for that, but as it contains
the first feature there is a lot of set up work involved.
Could be easier to review by opening the project on the IDE.
**Merge to `compass-app` not `main`**
cc. @ericwindmill
### Details
#### Folder structure
The project follows this folder structure:
- `lib/config/`: Put here any configuration files.
- `lib/config/dependencies.dart`: Configures the dependency tree (i.e.
Provider)
- `lib/data/models/`: Data classes
- `lib/data/repositories/`: Data repositories
- `lib/data/services/`: Data services (e.g. network API client)
- `lib/routing`: Everything related to navigation (could be moved to
`common`)
- `lib/ui/core/themes`: several theming classes are here: colors, text
styles and the app theme.
- `lib/ui/core/ui`: widget components to use across the app
- `lib/ui/<feature>/view_models`: ViewModels for the feature.
- `lib/ui/<feature>/widgets`: Widgets for the feature.
Unit tests also follow the same structure.
#### State Management
Most importantly, the project uses MVVM approach using `ChangeNotifier`
with the help of Provider.
This could be implemented without Provider or using any other way to
inject the VM into the UI classes.
#### Architecture approach
- Data follows a unidirectional flow from Repository -> Usecase ->
ViewModel -> Widgets -> User.
- The provided data Repository is using local data from the `assets`
folder, an abstract class is provided to hide this implementation detail
to the Usecase, and also to allow multiple implementations in the
future.
### Screenshots
### Extra notes:
- Moved the app code to the `app` folder. We need to create a `server`
project eventually.
### TODO:
- Integrate a logging framework instead of using `print()`.
- Do proper error handling.
- Improve image loading and caching.
- Complete tests with edge-cases and errors.
- Better Desktop UI.
## Pre-launch Checklist
- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
If you need help, consider asking for advice on the #hackers-devrel
channel on [Discord].
<!-- Links -->
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md
[CLA]: https://cla.developers.google.com/
[Discord]:
https://github.com/flutter/flutter/blob/master/docs/contributing/Chat.md
[Contributors Guide]:
https://github.com/flutter/samples/blob/main/CONTRIBUTING.md
Eric Windmill
Miguel Beltran
Eric Windmill