rework docs and readme

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/architecture.txt b/docs/architecture.txt
new file mode 100644
index 0000000..fb2d724
--- /dev/null
+++ b/docs/architecture.txt
@@ -0,0 +1,38 @@
+architecture
+============
+
+statix has the following components:
+  * bin: the CLI/entrypoint
+  * lib: library of lints and utilities to define these lints
+  * vfs: virtual filesystem
+  * macros: procedural macros to help define a lint
+
+
+bin
+---
+
+This is the main point of interaction between `statix` and
+the end user. It's output is human-readable and should also
+support JSON/errorfmt outputs for external tools to use.
+
+
+lib
+---
+
+A library of AST-based lints and utilities to help write
+those lints. It should be easy for newcomers to write lints
+without being familiar with the rest of the codebase.
+
+
+vfs
+---
+
+VFS is an in-memory filesystem. It provides cheap-to-copy
+handles (`FileId`s) to access paths and file contents.
+
+
+macros
+------
+
+This crate intends to be a helper layer to declare lints and
+their metadata.