mirror of
https://github.com/harivansh-afk/betterNAS.git
synced 2026-04-15 19:05:14 +00:00
doc scaaffold
This commit is contained in:
parent
8c4c10df5d
commit
b8b87a10d2
12 changed files with 278 additions and 263 deletions
68
docs/01-nas-node.md
Normal file
68
docs/01-nas-node.md
Normal file
|
|
@ -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.
|
||||
72
docs/02-control-plane.md
Normal file
72
docs/02-control-plane.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# betterNAS Part 2: Control Plane
|
||||
|
||||
This document describes the main backend that owns product semantics and coordinates the rest of the system.
|
||||
|
||||
## What it is
|
||||
|
||||
The control plane is the source of truth for betterNAS.
|
||||
|
||||
It should own:
|
||||
- users
|
||||
- devices
|
||||
- NAS nodes
|
||||
- storage exports
|
||||
- access grants
|
||||
- mount profiles
|
||||
- cloud access profiles
|
||||
- audit events
|
||||
|
||||
## What it does
|
||||
|
||||
- authenticates users and devices
|
||||
- tracks which NAS nodes exist
|
||||
- decides who can access which export
|
||||
- issues mount instructions to local devices
|
||||
- coordinates optional cloud/web access
|
||||
- stores the operational model of the whole product
|
||||
|
||||
## What it should not do
|
||||
|
||||
- proxy file bytes unless absolutely necessary
|
||||
- become a bottleneck in the data path
|
||||
- depend on Nextcloud as its system of record
|
||||
|
||||
## Diagram
|
||||
|
||||
```text
|
||||
betterNAS system
|
||||
|
||||
NAS node <---------> [THIS DOC] control plane <---------> local device
|
||||
| | |
|
||||
| | |
|
||||
+---------------------------+-----------------------+-----------+
|
||||
|
|
||||
v
|
||||
cloud/web layer
|
||||
```
|
||||
|
||||
## Core decisions
|
||||
|
||||
- The control plane is the product brain.
|
||||
- It should own policy and registry, not storage bytes.
|
||||
- It should stay standalone even if it integrates with Nextcloud.
|
||||
- It should issue access decisions, not act like a file server.
|
||||
|
||||
## Suggested first entities
|
||||
|
||||
- `User`
|
||||
- `Device`
|
||||
- `NasNode`
|
||||
- `StorageExport`
|
||||
- `AccessGrant`
|
||||
- `MountProfile`
|
||||
- `CloudProfile`
|
||||
- `AuditEvent`
|
||||
|
||||
## TODO
|
||||
|
||||
- Define the first real domain model and database schema.
|
||||
- Define auth between user device, NAS node, and control plane.
|
||||
- Define the API for mount profiles and access grants.
|
||||
- Define how the control plane tells the cloud/web layer what to expose.
|
||||
- Define direct-access vs relay behavior for unreachable NAS nodes.
|
||||
70
docs/03-local-device.md
Normal file
70
docs/03-local-device.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# betterNAS Part 3: Local Device
|
||||
|
||||
This document describes the software and user experience on the user's Mac or other local device.
|
||||
|
||||
## What it is
|
||||
|
||||
The local device layer is how a user actually mounts and uses their NAS.
|
||||
|
||||
It can start simple:
|
||||
- Finder + WebDAV mount
|
||||
- manual `Connect to Server`
|
||||
|
||||
It can later grow into:
|
||||
- a small desktop helper
|
||||
- one-click mount flows
|
||||
- auto-mount at login
|
||||
- status and reconnect behavior
|
||||
|
||||
## What it does
|
||||
|
||||
- authenticates the user to betterNAS
|
||||
- fetches allowed mount profiles from the control plane
|
||||
- mounts approved storage exports locally
|
||||
- gives the user a native-feeling way to browse files
|
||||
|
||||
## What it should not do
|
||||
|
||||
- invent its own permissions model
|
||||
- hardcode NAS endpoints outside the control plane
|
||||
- become tightly coupled to Nextcloud
|
||||
|
||||
## Diagram
|
||||
|
||||
```text
|
||||
betterNAS system
|
||||
|
||||
NAS node <---------> control plane <---------> [THIS DOC] local device
|
||||
| | |
|
||||
| | |
|
||||
+---------------------------+-----------------------+-----------+
|
||||
|
|
||||
v
|
||||
cloud/web layer
|
||||
```
|
||||
|
||||
## Core decisions
|
||||
|
||||
- V1 can rely on native Finder WebDAV mounting.
|
||||
- A lightweight helper app is likely enough before a full custom client.
|
||||
- The local device should consume mount profiles, not raw infrastructure details.
|
||||
|
||||
## User modes
|
||||
|
||||
### Mount mode
|
||||
|
||||
- user mounts a NAS export into Finder
|
||||
- files are browsed as a mounted remote disk
|
||||
|
||||
### Cloud mode
|
||||
|
||||
- user accesses the same storage through browser/mobile/cloud surfaces
|
||||
- this is not the same as a mounted filesystem
|
||||
|
||||
## TODO
|
||||
|
||||
- Define the mount profile format the control plane returns.
|
||||
- Decide what the first local UX is: manual Finder flow, helper app, or both.
|
||||
- Define credential storage and Keychain behavior.
|
||||
- Define auto-mount, reconnect, and offline expectations.
|
||||
- Define how the local device hands off to the cloud/web layer when mount mode is not enough.
|
||||
68
docs/04-cloud-web-layer.md
Normal file
68
docs/04-cloud-web-layer.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# betterNAS Part 4: Cloud / Web Layer
|
||||
|
||||
This document describes the optional browser, mobile, and cloud-drive style access layer.
|
||||
|
||||
## What it is
|
||||
|
||||
The cloud/web layer is the part of betterNAS that makes storage accessible beyond local mounts.
|
||||
|
||||
This is where we can reuse Nextcloud heavily for:
|
||||
- browser file UI
|
||||
- uploads and downloads
|
||||
- sharing links
|
||||
- WebDAV-based cloud access
|
||||
- mobile reference behavior
|
||||
|
||||
## What it does
|
||||
|
||||
- gives users a browser-based file experience
|
||||
- supports sharing and link-based access
|
||||
- gives us a cloud mode in addition to mount mode
|
||||
- can act as a reference surface while the main betterNAS product grows
|
||||
|
||||
## What it should not do
|
||||
|
||||
- own the product system of record
|
||||
- become the only way users access storage
|
||||
- swallow control-plane logic that should stay in betterNAS
|
||||
|
||||
## Diagram
|
||||
|
||||
```text
|
||||
betterNAS system
|
||||
|
||||
NAS node <---------> control plane <---------> local device
|
||||
| | |
|
||||
| | |
|
||||
+---------------------------+-----------------------+-----------+
|
||||
|
|
||||
v
|
||||
+----------------------+
|
||||
| [THIS DOC] cloud/web |
|
||||
|----------------------|
|
||||
| Nextcloud adapter |
|
||||
| browser UI |
|
||||
| sharing / mobile |
|
||||
+----------------------+
|
||||
```
|
||||
|
||||
## Core decisions
|
||||
|
||||
- The cloud/web layer is optional but very high leverage.
|
||||
- Nextcloud is a strong fit here because it already gives us file UI and sharing primitives.
|
||||
- It should sit beside mount mode, not replace it.
|
||||
|
||||
## Likely role of Nextcloud
|
||||
|
||||
- browser-based file UI
|
||||
- share and link management
|
||||
- optional mobile and cloud-drive style access
|
||||
- adapter over the same storage exports the control plane knows about
|
||||
|
||||
## TODO
|
||||
|
||||
- Decide whether Nextcloud is directly user-facing in v1 or mostly an adapter behind betterNAS.
|
||||
- Define how storage exports from the NAS node appear in the cloud/web layer.
|
||||
- Define how shares in this layer map back to control-plane access grants.
|
||||
- Define what mobile access looks like in v1.
|
||||
- Define branding and how much of the cloud/web layer stays stock vs customized.
|
||||
Loading…
Add table
Add a link
Reference in a new issue