doc scaaffold

docs/01-nas-node.md

@@ -0,0 +1,68 @@
+# betterNAS Part 1: NAS Node
+
+This document describes the software that runs on the actual NAS machine, VM, or workstation that owns the files.
+
+## What it is
+
+The NAS node is the machine that actually has the storage.
+
+It should run:
+- a WebDAV server
+- a small betterNAS node agent
+- declarative config via Nix
+- optional tunnel or relay connection if the machine is not directly reachable
+
+It should expose one or more storage exports such as:
+- `/data`
+- `/media`
+- `/backups`
+- `/vm-images`
+
+## What it does
+
+- serves the real file bytes
+- exposes chosen directories over WebDAV
+- registers itself with the control plane
+- reports health, identity, and available exports
+- optionally keeps an outbound connection alive for remote access
+
+## What it should not do
+
+- own user-facing product logic
+- decide permissions by itself
+- become the system of record for shares, devices, or policies
+
+## Diagram
+
+```text
+                            betterNAS system
+
+   local device  <------->  control plane  <------->  cloud/web layer
+        |                         |                          |
+        |                         |                          |
+        +-------------------------+--------------------------+
+                                  |
+                                  v
+                      +---------------------------+
+                      | [THIS DOC] NAS node       |
+                      |---------------------------|
+                      | WebDAV server             |
+                      | node agent                |
+                      | exported directories      |
+                      | optional tunnel/relay     |
+                      +---------------------------+
+```
+
+## Core decisions
+
+- The NAS node should be where WebDAV is served from whenever possible.
+- The control plane should configure access, but file bytes should flow from the node to the user device as directly as possible.
+- The node should be installable with a Nix module or flake so setup is reproducible.
+
+## TODO
+
+- Choose the WebDAV server we will standardize on for the node.
+- Define the node agent responsibilities and API back to the control plane.
+- Define the storage export model: path, label, capacity, tags, protocol support.
+- Define direct-access vs relayed-access behavior.
+- Define how the node connects to the cloud/web layer for optional Nextcloud integration.