Added architecture documentation (#544)

ARCHITECTURE.md

@@ -0,0 +1,48 @@
+# Rules Foreign CC - Architecture
+
+In this file, we describe how we think about the architecture
+of `rules_foreign_cc`. 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.
+
+## //foreign_cc
+
+This is the core package of the rules. It houses all rules which orchestrate
+builds in foreign (non-Bazel) c++ build systems.
+
+`//foreign_cc:defs.bzl` contains reexports of all core rules and should act
+as the single entry point for consumers of this project.
+
+`//foreign_cc/private` contains the implementation details of various rules
+and tools provided by this project. The symbols and signatures within this
+package should not be relied on and can change with no prior warning. Any
+functionality here should be moved into `//foreign_cc` if users want to
+interface with a stable API.
+
+## //examples (@rules_foreign_cc_examples)
+
+There are two primary types of examples, "Top Level" and "Third Party".
+"Top level" can also be thought of as integration tests for the rules as they
+should not contain any dependencies on code outside of the repo. "Third Party"
+examples are examples of the rules in existing external projects. For more
+detals on the examples, see
+[examples/README.md](./examples/README.md#third-party).
+
+## //test
+
+This package contains various tests of rules, rules which do not compile C++
+code. These tests can be thought of as unittests in mocked environments.
+
+## //toolchains
+
+Contains all toolchain information for supported build systems. There are a
+set of types of toolchains which you'll find here.
+
+1. `built_toolchains`
+2. `prebuilt_toolchains`
+3. `preinstalled_toolchains`
+
+For details on these types and the implemented toolchains, please see
+[`./toolchains/README.md`](./toolchains/README.md)

examples/README.md

@@ -1,8 +1,8 @@
 # Rules Foreign CC Examples
 
-## Top Level
+## Top-Level
 
-Top level examples should contain no dependencies outside of `rules_foreign_cc` directly and anything else in
+Top-level examples should contain no dependencies outside of `rules_foreign_cc` directly and anything else in
 it's directory. The directories should be prefixed with the type of rule they're associated with. Eg
 `cmake_with_data` (being a [cmake_external][cmake_external] example) and `configure_with_bazel_transitive`
 (being a [configure_make][configure_make] example).
@@ -12,8 +12,8 @@ it's directory. The directories should be prefixed with the type of rule they're
 Examples of building source from outside of `rules_foreign_cc` should be put in the `third_party` directory
 which is an isolated workspace that gets added to `rules_foreign_cc_examples` as an additional
 `rules_foreign_cc_examples_third_party` repository. In general, these are expected to be expensive to build
-so adding new things here should be done selectively. In the top level package of this workspace, there exsits
-test suites separated by operating system that all tests need to be registered to. The expected structure of
+so adding new things here should be done selectively. In the top-level package of this workspace, there are
+test suites separated by the operating system that all tests need to be registered with. The expected structure of
 any example in this workspace are as follows:
 
 ```text

examples/third_party/README.md

@@ -0,0 +1,5 @@
+# Rules Foreign CC Third Party Examples
+
+This package contains examples of `rules_foreign_cc` building common/popular third-party source code.
+
+For more details on how the examples here should be structured. Please see the documentation in [@rules_foreign_cc_examples//:README.md](../README.md#third-party).

toolchains/README.md

@@ -0,0 +1,16 @@
+# Rules Foreign CC Toolchains
+
+This package contains implementations for toolchains required for the supported build systems.
+
+## Built Toolchains
+
+These toolchains are for build tools that are built from source.
+
+## PreBuilt Toolchains
+
+These toolchains are for build tools that are built and stored at some remote site and downloaded when required by
+any target currently in the build graph.
+
+## PreInstalled Toolchains
+
+These toolchains are for build tools already installed on the host.