Add documentation of high-level design decisions.
Just to keep track of them.
Change-Id: I457fd91f03314454bb98d0d5b2a6ef37cca26b18
Reviewed-on: https://fuchsia-review.googlesource.com/c/shac-project/shac/+/868883
Reviewed-by: Oliver Newman <olivernewman@google.com>
Commit-Queue: Eli Ribble <eliribble@google.com>
diff --git a/README.md b/README.md
index 921217a..dbc0030 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@
## Documentation
+* [doc/design.md](doc/design.md): High-level design information.
* [doc/stdlib.md](doc/stdlib.md): shac runtime standard library documentation.
* [doc/stdlib.star](doc/stdlib.star): shac runtime standard library starlark
pseudo code.
diff --git a/doc/design.md b/doc/design.md
new file mode 100644
index 0000000..8387db0
--- /dev/null
+++ b/doc/design.md
@@ -0,0 +1,20 @@
+# Shac Design
+
+Why do we need another system for static code analysis? Shac does a few things that no known existing system does.
+
+At a high level, shac's goals are simple:
+
+ * Run checks safely
+ * _really fast_.
+
+By "fast" we mean "maximize utilization of available resources to minimize wall-clock delay for the user to get useful information."
+
+These goals inform the chosen design, which in turn produces various constraints. First, the design:
+
+ * Use a multi-pass system to determine which checks to run
+ * Run checks in parallel
+ * Use nsjail to sandbox checks
+
+The multi-pass system allows shac to determine which checks to run quickly. Then shac spawns threads to actually do the work of the checks.
+
+For each check shac provides a "passthrough" object that gives the check the ability to cache data. This helps well-written checks to continue to be fast by caching results of repetitive work. This passthrough also controls access to any external I/O like network calls.
