Add a pigeon sample that demonstrates a "realistic" integration scenario with middleware and business logic (#465)

add_to_app/README.md

@@ -10,11 +10,13 @@ standalone Flutter module.
   - Whether to build the Flutter module from source each time the app builds or
     rely on a separately pre-built module.
   - Whether plugins are needed by the Flutter module used in the app.
+* Show Flutter being integrated ergonomically with applications with existing
+  middleware and business logic data classes.
 
 ## Installing Cocoapods
 
 The iOS samples in this repo require the latest version of Cocoapods. To install
-it, run the following command on a MacOS machine:
+it, run the following command on a macOS machine:
 
 ```bash
 sudo gem install cocoapods
@@ -26,20 +28,26 @@ See https://guides.cocoapods.org/using/getting-started.html for more details.
 
 ### Flutter modules
 
-There are two Flutter modules included in the codebase:
+There are three Flutter modules included in the codebase:
 
 * `flutter_module` displays the dimensions of the screen, a button that
   increments a simple counter, and an optional exit button.
 * `flutter_module_using_plugin` does everything `flutter_module` does and adds
   another button that will open the Flutter documentation in a browser using the
   [`url_launcher`](https://pub.dev/packages/url_launcher) Flutter plugin.
+* `flutter_module_books` simulates an integration scenario with existing
+  platform business logic and middleware. It uses the [`pigeon`](https://pub.dev/packages/pigeon)
+  plugin to make integration easier by generating the platform channel
+  interop inside wrapper API and data classes that are shared between the
+  platform and Flutter.
+
 
 Before using them, you need to resolve the Flutter modules' dependencies. Do so
 by running this command from within the `flutter_module` and
 `flutter_module_using_plugin` directories:
 
 ```bash
-flutter packages get
+flutter pub get
 ```
 
 ### Android and iOS applications
@@ -139,6 +147,50 @@ Flutter frameworks, see this article in the Flutter GitHub wiki:
 
 https://flutter.dev/docs/development/add-to-app/ios/project-setup
 
+### `android_books` and `ios_books (TODO)`
+
+These apps integrate the `flutter_books` module using the simpler build-together
+project setup. They simulate a mock scenario where an existing book catalog
+list app already exists. Flutter is used to implement an additional book details
+page.
+
+* Similar to `android_fullscreen` and `ios_fullscreen`.
+* An existing books catalog app is already implemented in Kotlin and Swift.
+* The platform-side app has existing middleware constraints that should also
+  be the middleware foundation for the additional Flutter screen.
+    * On Android, the Kotlin app already uses GSON and OkHttp for networking and
+      references the Google Books API as a data source. These same libraries
+      also underpin the data fetched and shown in the Flutter screen.
+    * iOS TODO.
+* The platform application interfaces with the Flutter book details page using
+  idiomatic platform API conventions rather than Flutter conventions.
+    * On Android, the Flutter activity receives the book to show via activity
+      intent and returns the edited book by setting the result intent on the
+      activity. No Flutter concepts are leaked into the consumer activity.
+    * iOS TODO.
+* The [pigeon](https://pub.dev/packages/pigeon) plugin is used to generate
+  interop APIs and data classes. The same `Book` model class is used within the
+  Kotlin/Swift program, the Dart program and in the interop between Kotlin/Swift
+  and Dart. No manual platform channel plumbing needed for interop.
+    * The `api.dart/java/mm` files generated from the
+      `flutter_module_books/pigeon/schema.dart` file are checked into source
+      control. Therefore `pigeon` is only a dev dependency with no runtime
+      requirements.
+    * If the `schema.dart` is modified, the generated classes can be updated with
+
+        ```shell
+        flutter pub run pigeon \
+            --input pigeon/schema.dart \
+            --java_out ../android_books/app/src/main/java/dev/flutter/example/books/Api.java \
+            --java_package "dev.flutter.example.books"
+        ```
+
+      in the `flutter_module_books` directory.
+
+Once you've understood the basics of add-to-app with `android_fullscreen` and
+`ios_fullscreen`, this is a good sample to demonstrate how to integrate Flutter
+in a slightly more realistic setting with existing business logic.
+
 ## Questions/issues
 
 If you have a general question about incorporating Flutter into an existing