[infra] Add docs/ top level dir for explaining general interop concepts (#2705)
diff --git a/.github/pr-title-checker-config.json b/.github/pr-title-checker-config.json
index d80ed7a..7b47bd3 100644
--- a/.github/pr-title-checker-config.json
+++ b/.github/pr-title-checker-config.json
@@ -3,6 +3,7 @@
"prefixes": [
"[code_assets] ",
"[data_assets] ",
+ "[doc] ",
"[ffi] ",
"[ffigen] ",
"[hooks_runner] ",
diff --git a/README.md b/README.md
index 301d5be..7dc0338 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,10 @@
This repository is home to Dart packages related to FFI and native assets
building and bundling.
+## Documentation
+
+See the [doc](doc/) directory for more documentation.
+
## Packages
| Package | Description | Issues | Version |
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..d745860
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,19 @@
+# Documentation
+
+## Documentation applicable to all interop
+
+- [3 Layers in Dart Interop](interop-layers.md)
+
+## Guides
+
+- [C interop using dart:ffi](https://dart.dev/interop/c-interop) and the related
+ pages about interop with other languages.
+- [Flutter platform integration and native
+ interop](https://docs.flutter.dev/platform-integration) and the nested pages
+ related to binding to native code.
+- [Build and link hooks](https://dart.dev/tools/hooks).
+
+## Libraries and Packages
+
+- [dart:ffi API reference](https://api.dart.dev/stable/dart-ffi/dart-ffi-library.html)
+- Each package in this repository contains its own documentation in its respective `README.md` file.
diff --git a/doc/interop-layers.md b/doc/interop-layers.md
new file mode 100644
index 0000000..c4fc8b9
--- /dev/null
+++ b/doc/interop-layers.md
@@ -0,0 +1,97 @@
+# 3 Layers in Dart Interop
+
+Dart native interop can be structured into three layers:
+* Low level interop
+* Dart-y API
+* SDK-tailoring
+
+## Layer 1: Low level interop
+
+The goal of this layer is to provide a no-compromise, high-performance layer to
+make non-Dart APIs and libraries accessible from Dart. This layer is designed to
+be unopinionated, allowing threading, data transfer, and isolate life cycle to
+be built upon it. The APIs provided and generated are very thin Dart wrappers
+around the native APIs. They favor zero-cost abstractions such as [extension types][extension-types].
+While using this layer directly offers the most possibilities, it can lead to
+writing creole[^1] and presents footguns regarding memory management, threading, and
+the [isolate and VM life cycle][isolate-lifecycle].
+
+**Technologies in this layer:**
+* Low-level SDK libraries for calling native code, such as [`dart:ffi`][dart-ffi] and
+ [`dart:js_interop`][dart-js-interop].
+* Code generators such as [FFIgen][ffigen], [JNIgen][jnigen], and [web_generator][web-generator].
+
+**Design principles for tech in this layer:**
+* Performance comes first, usability second.
+* It is either implemented as a compiler backend or as a code generator built on
+ top of one.
+* Zero-configuration should be used if possible. The generator technologies do
+ not know how their code will be used, so it's preferable to generate code that
+ permits multiple usage patterns.
+
+## Layer 2: Dart-y API
+
+The objective of this layer is to offer a Dart-y API that bridges the impedance
+mismatch between Dart and the target language. Technologies in this layer are
+opinionated and may make domain-specific choices about value conversions
+(shallow or deep), concurrency models, etc.. They might sacrifice performance
+for improved usability and may provide adapters for implementing Dart types such
+as `Map` and `List`.
+
+**Technologies in this layer:**
+* Hand-written Dart wrappers around a layer 1 API for C libraries, such as
+ [SQLite3][sqlite3].
+* [Pigeon][pigeon], which decides on a full serialization and concurrency model.
+
+**Design principles for tech in this layer:**
+* APIs should have the feel of Dart APIs. No layer 1 types should be exposed,
+ and [Effective Dart][effective-dart] guidelines should be followed.
+* Users should not need to worry about the underlying native code. [Native
+ finalizers][native-finalizers] should be used to free resources.
+* APIs should be structured to work with Dart's threading and isolate life
+ cycle.
+* This layer is typically hand-crafted or built with a generator that has a high
+ degree of configuration fidelity.
+* If different platforms offer non-identical feature sets, the preference is to
+ publish platform-specific Dart APIs as packages and then build a
+ platform-agnostic package on top of them.
+
+## Layer 3: SDK-tailoring (optional)
+
+This layer's purpose is to provide integration with specific SDKs built on Dart.
+This layer is optional. If a solution can be provided as a layer 2 solution, it
+should be, as this makes it reusable across multiple SDKs.
+
+**Technologies in this layer:**
+* [Flutter Plugin API][flutter-plugin-api]: Provides access to Flutter-defined elements such as [App
+ lifecycle][app-lifecycle], [Android Context][android-context], etc.
+* [Flutter Plugins][flutter-plugins]: These can, for example, hide the Android Context from the API
+ they expose to a Dart developer.
+
+## Cross-layer design principles
+
+Layer 2 solutions have the option to provide "native escape hatches" to layer 1.
+This allows layer 1 to give immediate access to new OS APIs while layer 2 is
+being updated.
+
+[^1]: A "creole" language, in this context, refers to code that is technically
+ Dart but is written using the objects and patterns of the underlying native
+ language (e.g., Objective-C). This creates a "mixed" language with its own
+ learning curve and challenges, particularly around memory management and
+ concurrency.
+
+[android-context]: https://developer.android.com/reference/android/content/Context
+[app-lifecycle]: https://api.flutter.dev/flutter/widgets/AppLifecycleListener-class.html
+[dart-ffi]: https://api.dart.dev/dart-ffi/
+[dart-js-interop]: https://api.dart.dev/dart-js_interop/
+[effective-dart]: https://dart.dev/guides/language/effective-dart
+[extension-types]: https://dart.dev/language/extension-types
+[ffigen]: ../pkgs/ffigen/
+[flutter-plugin-api]: https://docs.flutter.dev/packages-and-plugins/developing-packages
+[flutter-plugins]: https://docs.flutter.dev/packages-and-plugins/using-packages
+[isolate-lifecycle]: https://dart.dev/language/concurrency
+[jnigen]: ../pkgs/jnigen/
+[native-finalizers]: https://api.dart.dev/dart-ffi/NativeFinalizer-class.html
+[pigeon]: https://pub.dev/packages/pigeon
+[sqlite3]: https://pub.dev/packages/sqlite3
+[web-generator]: https://github.com/dart-lang/web/tree/main/web_generator
