docs: add Android Interfaces cross-reference section to README

Explain the ndk/jni/aidl ecosystem with a Mermaid diagram showing
how each library connects to the Android platform, a comparison
table, and guidance on when to use which.

Author: xaionaro@dx.center

README.md

@@ -7,6 +7,65 @@
 
 Idiomatic Go bindings for the Android NDK, auto-generated from C headers to ensure full coverage and easy maintenance.
 
+## Android Interfaces for Go
+
+This project is part of a family of three Go libraries that cover the major Android interface surfaces. Each wraps a different layer of the Android platform:
+
+```mermaid
+graph TD
+    subgraph "Go application"
+        GO["Go code"]
+    end
+
+    subgraph "Interface libraries"
+        NDK["<b>ndk</b><br/>C API bindings via cgo"]
+        JNI["<b>jni</b><br/>Java API bindings via JNI+cgo"]
+        AIDL["<b>aidl</b><br/>Binder IPC, pure Go"]
+    end
+
+    subgraph "Android platform"
+        CAPI["NDK C libraries<br/>(libcamera2ndk, libaaudio,<br/>libEGL, libvulkan, ...)"]
+        JAVA["Java SDK<br/>(android.bluetooth,<br/>android.location, ...)"]
+        BINDER["/dev/binder<br/>kernel driver"]
+        SYSSVCS["System services<br/>(ActivityManager,<br/>PowerManager, ...)"]
+    end
+
+    GO --> NDK
+    GO --> JNI
+    GO --> AIDL
+
+    NDK -- "cgo / #include" --> CAPI
+    JNI -- "cgo / JNIEnv*" --> JAVA
+    AIDL -- "ioctl syscalls" --> BINDER
+    BINDER --> SYSSVCS
+    JAVA -. "internally uses" .-> BINDER
+    CAPI -. "some use" .-> BINDER
+```
+
+| Library | Interface | Requires | Best for |
+|---|---|---|---|
+| **[ndk](https://github.com/xaionaro-go/ndk)** (this project) | Android NDK C APIs | cgo + NDK toolchain | High-performance hardware access: camera, audio, sensors, OpenGL/Vulkan, media codecs |
+| **[jni](https://github.com/xaionaro-go/jni)** | Java Android SDK via JNI | cgo + JNI + JVM/ART | Java-only APIs with no NDK equivalent: Bluetooth, WiFi, NFC, location, telephony, content providers |
+| **[aidl](https://github.com/xaionaro-go/aidl)** | Binder IPC (system services) | pure Go (no cgo) | Direct system service calls without Java: works on non-Android Linux with binder, minimal footprint |
+
+### When to use which
+
+- **Start with ndk** when the NDK provides a C API for what you need (camera, audio, sensors, EGL/Vulkan, media codecs). These are the lowest-latency, lowest-overhead bindings since they go straight from Go to the C library via cgo.
+
+- **Use jni** when you need a Java Android SDK API that the NDK does not expose. Examples: Bluetooth discovery, WiFi P2P, NFC tag reading, location services, telephony, content providers, notifications. JNI is also the right choice when you need to interact with Java components (Activities, Services, BroadcastReceivers) or when you need the gRPC remote-access layer.
+
+- **Use aidl** when you want pure-Go access to Android system services without any cgo dependency. This is ideal for lightweight tools, CLI programs, or scenarios where you want to talk to the binder driver from a non-Android Linux system. AIDL covers the same system services that Java SDK wraps (ActivityManager, PowerManager, etc.) but at the wire-protocol level.
+
+- **Combine them** when your application needs multiple layers. For example, a streaming app might use **ndk** for camera capture and audio encoding, **jni** for Bluetooth controller discovery, and **aidl** for querying battery status from a companion daemon.
+
+### How they relate to each other
+
+All three libraries talk to the same Android system services, but through different paths:
+
+- The **NDK C APIs** are provided by Google as stable C interfaces to Android platform features. Some (camera, sensors, audio) internally use binder IPC to talk to system services; others (EGL, Vulkan, OpenGL) talk directly to kernel drivers. The `ndk` library wraps these C APIs via cgo.
+- The **Java SDK** uses binder IPC internally for system service access (BluetoothManager, LocationManager, etc.), routing calls through the Android Runtime (ART/Dalvik). The `jni` library calls into these Java APIs via the JNI C interface and cgo.
+- The **AIDL binder protocol** is the underlying IPC mechanism that system-facing NDK and Java SDK APIs use. The `aidl` library implements this protocol directly in pure Go, bypassing both C and Java layers entirely.
+
 ## Requirements
 
 - **Android NDK r28** (28.0.13004108) or later