diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e9f8f61
--- /dev/null
+++ b/README.md
@@ -0,0 +1,21 @@
+# hacc nixfiles
+
+welcome to hacc nixfiles (haccfiles). this is the code describing our nix-based infrastructure.
+
+## structure
+
+- `default.nix`: Entrypoint to the config
+- `common/`: configuration common to all hosts
+- `desktop/`: desktop-relevant communication
+- `modules/`: home-grown modules for hacc-specific services
+- `nix/`: sources files, managed with niv
+- `pkgs/`: packages we built and don't want to upstream
+
+## working with the haccfiles
+
+deploy:
+``` shell
+nix build -f . deploy.$hostname && ./result switch
+```
+
+`$hostname` can be replaced with any hostname or group