[embedder] General architecture documentation.

Fixed: 115343
Change-Id: I051f366dcb915267550d50f8a813dedd67d57d36
Reviewed-on: https://fuchsia-review.googlesource.com/c/flutter-embedder/+/762475
Reviewed-by: Ben Bergkamp <benbergkamp@google.com>
diff --git a/README.md b/README.md
index c7f371c..2f39f96 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,20 @@
-1. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location,
+1. Clone this repository.
+   ```sh
+   git clone https://fuchsia.googlesource.com/flutter-embedder
+   ```
+2. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location,
    for example `~/flutter-embedder`.
    export FUCHSIA_EMBEDDER_DIR=$HOME/flutter-embedder
-2. Bootstrap the repository's dependencies:
+3. Bootstrap the repository's dependencies:
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..02ae909
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,38 @@
+# Documentation
+This folder contains high-level documentation for Flutter on Fuchsia.
+To run an example component on Fuchsia, see the
+[top-level README](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/README.md).
+## Architecture docs
+- [_`architecture.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/architecture.md):
+  General overview of how the Flutter
+  Embedder for Fuchsia works.
+- [_`pointer_input.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/pointer_input.md):
+  How mouse and touch input works.
+- [_`software_rendering.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/software_rendering.md):
+  How software (CPU-based) rendering works.
+## Workflow docs
+- [_`debugging.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md):
+  How to attach a debugger to a Flutter component.
+- [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md):
+  A suggested workflow for uploading
+  changes to this repository.
+- [_`making_engine_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md):
+  How to test changes to
+  the [Flutter Engine](https://github.com/flutter/engine) code with a Flutter component.
+- [_`testing_fuchsia_sdk_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md):
+  How to test changes to
+  the [Fuchsia platform](https://fuchsia.googlesource.com/fuchsia) code with a Flutter component.
+- [_`updating_dependencies.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/updating_dependencies.md):
+  How to update this repository's third_party dependencies.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..2ccbd75
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,81 @@
+# How a Flutter component works
+For a very detailed overview of Flutter architecture on all platforms,
+see [this doc](https://docs.flutter.dev/resources/architectural-overview).
+A Flutter component for Fuchsia is an [ELF binary](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format)
+that is built and run using Fuchsia's [Bazel SDK](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0139_bazel_sdk).
+The component is launched by 
+[Fuchsia's ELF runner](https://fuchsia.dev/fuchsia-src/concepts/components/v2/elf_runner)
+(there is no longer a separate Flutter runner or Dart runner).
+Building and running an example Flutter component is done by:
+1. Compiling the Flutter application to get a folder of compiled assets
+   ([snapshot](https://mrale.ph/dartvm/#how-does-dart-vm-run-your-code), fonts, images).
+   This is currently done with the Flutter CLI using `flutter build bundle`.
+   This only supports JIT compilation. To support AOT compilation, we should switch to
+   using the Dart SDK's tools instead (see
+   [this doc](https://github.com/flutter/flutter/wiki/Custom-Flutter-Engine-Embedding-in-AOT-Mode#the-hard-way)
+   for reference).
+2. [Packaging](https://fuchsia.dev/fuchsia-src/concepts/packages/package)
+   these assets together with the embedder executable and shared libraries.
+   See [_"Package layout"_](#package-layout) for details.
+3. Running the embedder executable with the ELF runner. This is handled
+   by the Bazel SDK.
+   We pass the path to the compiled assets as an argument
+   [here](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/embedder/meta/embedder.cml#18).
+Running the application using the assets is handled by `libflutter_engine.so`,
+a shared library from the [Flutter Engine repository](https://github.com/flutter/engine).
+We interact with `libflutter_engine.so` using
+![embedder architecture diagram](images/embedder_architecture.png)
+## Package layout
+The compiled Flutter component's package has three main folders:
+- **`bin/embedder`**: The executable.
+- **`data/flutter_assets/`**: The compiled assets of the Flutter app that should
+  be run by the executable.
+- **`lib/`**: Shared libraries that are used by `bin/embedder`.
+  Notably, `lib/libflutter_engine.so` is the Flutter Engine code that
+  `bin/embedder` uses to run the Flutter app.
+When building and running a Flutter example, the full package contents are printed
+for debugging.
+## Threading model
+The easiest way to understand how threading works in Flutter
+is to
+[attach a debugger in VS Code](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md#attaching-a-debugger-from-vscode)
+and break on a function that you're interested in. VS Code will tell
+you what thread the code is running on.
+![threads in VS Code](images/vscode_thread_model.png)
+Some notable threads:
+- Platform thread (`initial-thread`): The thread that `main()` runs on.
+    - We connect to all
+      [FIDL services](https://fuchsia.dev/fuchsia-src/concepts/fidl/overview)
+      on this thread and
+      [platform messages](https://docs.flutter.dev/development/platform-integration/platform-channels)
+      are sent on this thread.
+    - Async requests and responses to FIDL services are handled by an async loop that is started by `FlutterEngineRun`.
+- Raster thread (`io.flutter.raster`): Handles rendering logic for Flutter.
+    - Callbacks for rendering are called on this thread.
diff --git a/docs/debugging.md b/docs/debugging.md
index cad54ae..7cc08a9 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -2,10 +2,11 @@
 There are two ways to attach a debugger to example components:
-- **From the command-line interface (CLI).** This is currently
-  the most well-supported way.
+- [**From the command-line interface (CLI).**](#attaching-a-debugger-from-the-cli)
+  This is currently the most well-supported way.
-- **From VSCode.** This works for attaching breakpoints and stepping
+- [**From VSCode.**](#attaching-a-debugger-from-vscode)
+  This works for attaching breakpoints and stepping
   through the code but more advanced commands may not work (see
   [known issues](https://bugs.fuchsia.dev/p/fuchsia/issues/list?q=component%3ADeveloperExperience%3EFuchsiaExtensionForVSCode%20zxdb&can=2)).
diff --git a/docs/images/embedder_architecture.png b/docs/images/embedder_architecture.png
new file mode 100644
index 0000000..3153b44
--- /dev/null
+++ b/docs/images/embedder_architecture.png
Binary files differ
diff --git a/docs/images/vscode_thread_model.png b/docs/images/vscode_thread_model.png
new file mode 100644
index 0000000..8cc473c
--- /dev/null
+++ b/docs/images/vscode_thread_model.png
Binary files differ