diff --git a/services/syncbase/bridge/cgo/README.md b/services/syncbase/bridge/cgo/README.md
index 7351be8..f703589 100644
--- a/services/syncbase/bridge/cgo/README.md
+++ b/services/syncbase/bridge/cgo/README.md
@@ -6,3 +6,37 @@
 For the time being, we provide a `Makefile` to build C archives for all target
 platforms. Eventually, we'll integrate C archive compilation with the `jiri`
 tool.
+
+# JNI
+
+Java expects functions that have names and arguments that match the `native`
+declarations from the `.java` files located in `java/io/v/syncbase/internal`.
+
+Layout:
+
+- `jni.go`: the JNI functions expected by Java.
+- `jni_util.go`: helper functions to find Java classes and retrieve IDs for
+   object fields and methods.
+- `jni_lib.go`: types and functions to cache the field and method IDs for all
+   the classes the code needs to touch.
+- `jni_types.go`: methods and functions to convert between Java and the types
+   declared in `lib.h`; counterpart of `types.go`.
+- `jni_wrapper.{h,c}`: trampoline functions that compensate for the fact that Go
+   cannot call a function pointer.
+
+Some design notes:
+
+- looking up classes/interfaces, methods and field IDs is expensive. The global
+  variables named like `fooClass` from `jni.go` cache all we need for a class
+  `foo`. The load is done in `JNI_OnLoad`, a function that is called each time
+  the our library is loaded (typically, using `System.loadLibrary()`).
+- some of the `extractToJava()` methods and `newVFoo()` functions are in
+  `jni.go` instead of `jni_types.go` to avoid some
+  _"inconsistent definitions"_ errors.
+- the `extractToJava()` methods convert from low-level types like
+  `v23_syncbase_Foo` to their Java equivalents. The `extract()` methods convert
+  to Go equivalents. Both `extract()` and `extractToJava()` will free all the
+  pointers inside the primitive types they are extracting from.
+- the `free()` methods are idempotent.
+- we use `panic()` to enforce certain invariants (enough memory, existence of
+  classes, methods, fields, etc) and to keep the code simple.
\ No newline at end of file