From ca4315a92d2de2772b48af49170aab067bd5fa69 Mon Sep 17 00:00:00 2001 From: Harivansh Rathi Date: Wed, 1 Apr 2026 02:52:13 +0000 Subject: [PATCH] brought together --- docs/05-build-plan.md | 230 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 docs/05-build-plan.md diff --git a/docs/05-build-plan.md b/docs/05-build-plan.md new file mode 100644 index 0000000..6934fb9 --- /dev/null +++ b/docs/05-build-plan.md @@ -0,0 +1,230 @@ +# betterNAS Part 5: Build Plan + +This document ties the other four parts together. + +It answers four questions: +- how the full system fits together +- where each part starts +- what we should steal from existing tools +- what we must write ourselves + +## The full system + +```text + betterNAS build plan + + [2] control plane + +--------------------------------+ + | API + policy + registry + UI | + +--------+---------------+-------+ + | | + control/API | | cloud adapter + v v + [1] NAS node [4] cloud/web layer + +------------------+ +-------------------+ + | WebDAV + agent | | Nextcloud adapter | + | real storage | | browser/mobile | + +---------+--------+ +---------+---------+ + | ^ + | mount profile | + v | + [3] local device ---------------+ + +----------------------+ + | Finder mount/helper | + | native user entry | + +----------------------+ +``` + +## The core rule + +The control plane owns product semantics. + +The other three parts are execution surfaces: +- the NAS node serves storage +- the local device mounts and uses storage +- the cloud/web layer exposes storage through browser and mobile-friendly flows + +## What we steal vs write + +| Part | Steal first | Write ourselves | +|---|---|---| +| NAS node | NixOS/Nix module patterns, existing WebDAV servers | node agent, export model, node registration flow | +| Control plane | existing repo scaffold, TS stack, Postgres/Redis patterns | product domain model, policy engine, mount/cloud APIs, registry | +| Local device | Finder WebDAV mount, macOS Keychain, later maybe launch agent patterns | helper app, mount profile handling, auto-mount UX | +| Cloud/web layer | Nextcloud server, Nextcloud shell app, Nextcloud share/file UI, Nextcloud mobile references | betterNAS integration layer, mapping between product model and Nextcloud, later branded UI | + +## Where each part should start + +## 1. NAS node + +Start from: +- Nix flake / module +- a standard WebDAV server +- a very small agent process + +Do not start by writing: +- custom storage protocol +- custom file server +- custom sync engine + +The NAS node should be boring and reproducible. + +## 2. Control plane + +Start from: +- the current `exapps/control-plane` scaffold +- TypeScript +- Postgres +- Redis +- standalone API mindset + +Do not start by writing: +- microservices +- custom file transport +- a proxy that sits in the middle of every file transfer + +This is the first real thing we should build. + +## 3. Local device + +Start from: +- native Finder `Connect to Server` +- WebDAV mount URLs issued by the control plane + +Then later add: +- a lightweight helper app +- Keychain integration +- auto-mount at login + +Do not start by writing: +- a full custom desktop sync client +- a Finder extension +- a new filesystem driver + +## 4. Cloud / web layer + +Start from: +- stock Nextcloud +- current shell app +- Nextcloud browser/share/mobile primitives + +Then later add: +- betterNAS-specific integration pages +- standalone control-plane web UI +- custom branding or replacement UI where justified + +Do not start by writing: +- a full custom browser file manager +- a custom mobile client +- a custom sharing stack + +## Recommended build order + +### Phase A: make the storage path real + +1. NAS node can expose a directory over WebDAV +2. control plane can register the node and its exports +3. local device can mount that export in Finder + +This is the shortest path to a real product loop. + +### Phase B: make the product model real + +1. add users, devices, NAS nodes, exports, grants, mount profiles +2. add auth and policy +3. add a simple standalone web UI for admin/control use + +This is where betterNAS becomes its own product. + +### Phase C: add cloud mode + +1. connect the same storage into Nextcloud +2. expose browser/mobile/share flows +3. map Nextcloud behavior back to betterNAS product semantics + +This is high leverage, but should not block Phase A. + +## External parts we should deliberately reuse + +### NAS node +- WebDAV server implementation +- Nix module patterns + +### Control plane +- current TypeScript repo scaffold +- Postgres +- Redis + +### Local device +- Finder's native WebDAV mounting +- macOS credential storage + +### Cloud/web layer +- Nextcloud server +- Nextcloud app shell +- Nextcloud share/browser behavior +- Nextcloud mobile and desktop references + +## From-scratch parts we should deliberately own + +### NAS node +- node enrollment +- export registration +- machine identity and health reporting + +### Control plane +- full backend domain model +- access and policy model +- mount profile generation +- cloud profile generation +- audit and registry + +### Local device +- user-friendly mounting workflow +- helper app if needed +- local mount orchestration + +### Cloud/web layer +- betterNAS-to-Nextcloud mapping layer +- standalone betterNAS product UI over time + +## First scaffolds to use + +| Part | First scaffold | +|---|---| +| NAS node | Nix flake/module + WebDAV server service config | +| Control plane | current TypeScript control-plane service scaffold | +| Local device | documented Finder mount flow, then lightweight helper app | +| Cloud/web layer | current Nextcloud scaffold and shell app | + +## What not to overbuild early + +- custom sync engine +- custom desktop client +- custom mobile app +- many backend services +- control-plane-in-the-data-path file proxy + +Those can come later if the simpler stack proves insufficient. + +## Build goal for V1 + +V1 should prove one clean loop: + +```text +user picks NAS export in betterNAS UI +-> control plane issues mount profile +-> local device mounts WebDAV export +-> user sees and uses files in Finder +-> optional Nextcloud surface exposes the same storage in cloud mode +``` + +If that loop works, the architecture is sound. + +## TODO + +- Choose the exact WebDAV server for the NAS node. +- Decide the first Nix module layout for node installation. +- Define the first database-backed control-plane entities. +- Decide whether the local device starts as documentation-only or a helper app. +- Decide when the Nextcloud cloud/web layer becomes user-facing in v1.