Add ARCHITECTURE.md (#596)
In this file I hope to describe how we think about the architecture
of rules_rust. It's goal is to help contributors orient themselves, and to
document code restrictions and assumptions.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..c302041
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,58 @@
+# Rules Rust - Architecture
+
+In this file we describe how we think about the architecture
+of `rules_rust`. It's goal is to help contributors orient themselves, and to
+document code restrictions and assumptions.
+
+In general we try to follow the common standard defined by
+https://docs.bazel.build/versions/master/skylark/deploying.html.
+
+## //rust
+
+This is the core package of the rules. It contains all the core rules such as
+`rust_binary` and `rust_library`. It also contains `rust_common`, a Starlark
+struct providing all rules_rust APIs that one might need when writing custom
+rules integrating with rules_rust.
+
+`//rust` and all its subpackages have to be standalone. Users who only need
+the core rules should be able to ignore all other packages.
+
+`//rust:defs.bzl` is the file that all users of `rules_rust` will be using.
+Everything in this file can be used (dependend on) and is supported (though
+stability is not currently guaranteed across commits, see
+[#600](https://github.com/bazelbuild/rules_rust/issues/600)). Typically this
+file reexports definitions from other files, typically from `//rust/private`.
+Also other packages in `rules_rust` should access core rules through the public
+API only. We expect dogfooding our own APIs increases their
+quality.
+
+`//rust/private` package contains code rule implementation. This file can only
+depend on `//rust` and its subpackages. Exceptions are Bazel's builtin packages
+and public APIs of other rules (such as `rules_cc`). Depending on
+`//rust/private` from packages other than `//rust` is not supported, we reserve
+the right to change anything there and not tell anybody.
+
+When core rules need custom tools (such as process wrapper, launcher, test
+runner, and so on), they should be stored in `//rust/tools` (for public tools)
+or in `//rust/private/tools` (for private tools). These should:
+
+* be essential (it does not make sense to have core rules without them)
+* have few or no third party dependencies, and their third party dependencies
+ should be checked in.
+* be usable for cross compilation
+* have only essential requirements on the host system (requiring that a custom
+ library is installed on the system is frowned upon)
+
+## //examples (@examples)
+
+Examples package is actually a local repository. This repository can have
+additional dependencies on anything that helps demonstrate an example. Non
+trivial examples should have an accompanying README.md file.
+
+The goal of examples is to demonstrate usage of `rules_rust`, not to test code.
+Use `//test` for testing.
+
+## //test
+
+Contains unit (in `//test/unit`) and integration tests. CI configuration is
+stored in .bazelci.
