harivansh-afk/betterNAS
1
1
Fork 0
mirror of https://github.com/harivansh-afk/betterNAS.git synced 2026-04-15 13:03:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

move

Browse source
This commit is contained in:
Harivansh Rathi 2026-04-01 23:39:43 -04:00
parent 23e0baa1ef
commit 93d610db29
4 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/repository-root/README.md Normal file
View file

@ -0,0 +1,8 @@
betterNAS lets you mount remote machines as native Finder volumes on your Mac.
Install a small agent on any box with files you care about, and it shows up in Finder like a local drive.
No sync clients, no special apps - just your files, where you expect them.
The plan is bigger: phone, laptop, agents, all seeing the same filesystem.
A modular backup layer you actually use day-to-day, and a way to run agents on your own hardware without handing over the keys.
<img width="1330" height="614" alt="image" src="https://github.com/user-attachments/assets/f4cfe135-505f-4ce1-bbb3-1f1d47821f8f" />

15
docs/repository-root/TODO.md Normal file
View file

@ -0,0 +1,15 @@
# TODO
- [x] Remove the temporary TypeScript SDK layer so shared interfaces only come from `packages/contracts`.
- [x] Switch the monorepo from `npm` workspaces to `pnpm`.
- [x] Add root formatting, verification, and Go formatting rails.
- [x] Add hard boundary checks so apps and packages cannot drift across lanes with private imports.
- [x] Make the first contract-backed mount loop real: node registration, export inventory, mount profile issuance, and a Finder-mountable WebDAV export.
- [x] Prove the first manual remote-host WebDAV mount from a Mac over SSH tunnel.
- [ ] Surface exports and issued mount URLs in the web control plane.
- [ ] Add durable control-server storage for nodes, exports, grants, and mount profiles.
- [ ] Define the self-hosted deployment shape for the full stack on a NAS device.
- [ ] Define the Nix/module shape for installing the node-service on a NAS host.
- [ ] Decide whether the node-service should self-register or stay bootstrap-registered.
- [ ] Decide whether browser file viewing belongs in V1 web control plane or later.
- [ ] Define if and when the optional Nextcloud adapter comes back into scope.

51
docs/repository-root/control.md Normal file
View file

@ -0,0 +1,51 @@
# Control
This repo is the coordination and implementation ground for betterNAS.
Use it for:
- shared contracts
- architecture and planning docs
- runtime scripts
- stack verification
- implementation of the self-hosted stack
## Current product focus
The default betterNAS product is:
- self-hosted on the user's NAS
- WebDAV-first
- Finder-mountable
- managed through a web control plane
The main parts are:
- `node-service`
- `apps/node-agent`
- `control-server`
- `apps/control-plane`
- `web control plane`
- `apps/web`
- `optional cloud adapter`
- `apps/nextcloud-app`
## Rules
- shared interface changes land in `packages/contracts` first
- `docs/architecture.md` is the canonical architecture contract
- the self-hosted mount flow is the critical path
- optional Nextcloud work must not drive the main architecture
## Command surface
- `pnpm verify`
- static verification
- `pnpm stack:up`
- boot the self-hosted stack
- `pnpm stack:verify`
- verify the working stack
- `pnpm stack:down --volumes`
- tear the stack down cleanly
- `pnpm agent:verify`
- bootstrap, verify, boot, and stack-verify in one loop

264
docs/repository-root/skeleton.md Normal file
View file

@ -0,0 +1,264 @@
# betterNAS Skeleton
This is the root build skeleton for the monorepo.
Its job is simple:
- lock the repo shape
- lock the language per runtime
- lock the first shared contract surface
- keep the self-hosted stack clear
- make later scoped execution runs easier
## Repo shape
```text
betterNAS/
├── apps/
│ ├── web/ # Next.js web control plane
│ ├── control-plane/ # Go control-server
│ ├── node-agent/ # Go node-service and WebDAV runtime
│ └── nextcloud-app/ # optional Nextcloud adapter
├── packages/
│ ├── contracts/ # canonical OpenAPI, schemas, TS types
│ ├── ui/ # shared React UI
│ ├── eslint-config/ # shared lint config
│ └── typescript-config/ # shared TS config
├── infra/
│ └── docker/ # self-hosted stack for local proof
├── docs/ # architecture and build docs
├── scripts/ # bootstrap, verify, and stack helpers
├── go.work # Go workspace
├── turbo.json # Turborepo task graph
└── skeleton.md # this file
```
## Runtime and language choices
| Part | Language | Why |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| `apps/web` | TypeScript + Next.js | fastest way to build the control-plane UI |
| `apps/control-plane` | Go | strong backend baseline, static binaries, simple self-hosting |
| `apps/node-agent` | Go | best fit for NAS runtime, WebDAV serving, and future Nix deployment |
| `apps/nextcloud-app` | PHP | native language for an optional Nextcloud adapter |
| `packages/contracts` | OpenAPI + JSON Schema + TypeScript | language-neutral source of truth with practical frontend ergonomics |
## Default deployment model
The default product story is self-hosted:
```text
self-hosted betterNAS stack on user's NAS
+--------------------------------------------+
| web control plane |
| user opens this in browser |
+-------------------+------------------------+
|
v
+--------------------------------------------+
| control-server |
| auth / nodes / exports / grants |
| mount profile issuance |
+-------------------+------------------------+
|
v
+--------------------------------------------+
| node-service |
| WebDAV export runtime |
| real NAS files |
+--------------------------------------------+
user Mac
|
+--> browser -> web control plane
|
+--> Finder -> issued WebDAV mount URL
```
Optional later shape:
- hosted control-server
- hosted web control plane
- optional Nextcloud adapter for cloud/mobile/share surfaces
Those are not required for the core betterNAS product loop.
## Canonical contract rule
The source of truth for shared interfaces is:
1. [`docs/architecture.md`](./docs/architecture.md)
2. [`packages/contracts/openapi/betternas.v1.yaml`](./packages/contracts/openapi/betternas.v1.yaml)
3. [`packages/contracts/schemas`](./packages/contracts/schemas)
4. [`packages/contracts/src`](./packages/contracts/src)
Agents must not invent shared request or response shapes outside those
locations.
## Implementation lanes
```text
shared write surface
+-------------------------------------------+
| docs/architecture.md |
| packages/contracts/ |
+----------------+--------------------------+
|
+---------------+----------------+----------------+
| | |
v v v
node-service control-server web control plane
optional later:
nextcloud adapter
```
Allowed ownership:
- node-service lane
- `apps/node-agent`
- future `infra/nix` host module work
- control-server lane
- `apps/control-plane`
- web control plane lane
- `apps/web`
- optional adapter lane
- `apps/nextcloud-app`
- shared contract lane
- `packages/contracts`
- `docs/architecture.md`
## The first verification loop
```text
[node-service]
serves WebDAV export
|
v
[control-server]
registers node + export
issues mount profile
|
v
[web control plane]
shows export and mount action
|
v
[local device]
mounts in Finder
```
This is the main product loop.
## Upstream references to steal from
### Monorepo and web
- Turborepo `create-turbo`
- https://turborepo.dev/repo/docs/reference/create-turbo
- why: monorepo base scaffold
- Turborepo structuring guide
- https://turborepo.dev/repo/docs/crafting-your-repository/structuring-a-repository
- why: package boundaries and task graph rules
- Next.js backend-for-frontend guide
- https://nextjs.org/docs/app/guides/backend-for-frontend
- why: keep Next.js as UI and orchestration surface, not the source-of-truth backend
### Go control-server
- Go routing enhancements
- https://go.dev/blog/routing-enhancements
- why: stdlib-first routing baseline
- `pgx`
- https://github.com/jackc/pgx
- why: Postgres-first Go driver
- `sqlc`
- https://github.com/sqlc-dev/sqlc
- why: typed query generation
- `go-redis`
- https://github.com/redis/go-redis
- why: primary Redis client
- `asynq`
- https://github.com/hibiken/asynq
- why: practical Redis-backed job system
- `oapi-codegen`
- https://github.com/oapi-codegen/oapi-codegen
- why: generate surfaces from OpenAPI with less drift
### Node-service and WebDAV
- Go WebDAV package
- https://pkg.go.dev/golang.org/x/net/webdav
- why: embeddable WebDAV server implementation
- `hacdias/webdav`
- https://github.com/hacdias/webdav
- why: small standalone WebDAV reference
- NixOS manual
- https://nixos.org/manual/nixos/stable/
- why: declarative host setup and service wiring
### Local mount UX
- Finder `Connect to Server`
- https://support.apple.com/en-lamr/guide/mac-help/mchlp3015/mac
- why: native mount UX baseline
- Finder WebDAV mounting
- https://support.apple.com/is-is/guide/mac-help/mchlp1546/mac
- why: exact v1 mount path
- Keychain data protection
- https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web
- why: local credential storage model
- WebDAV RFC 4918
- https://www.rfc-editor.org/rfc/rfc4918
- why: protocol semantics and edge cases
### Optional cloud adapter
- Nextcloud app template
- https://github.com/nextcloud/app_template
- why: thin adapter app reference
- Nextcloud WebDAV docs
- https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html
- why: protocol/client behavior reference
## What we steal vs what we own
### Steal
- Turborepo repo shape and task graph
- Next.js web-app conventions
- Go stdlib and proven Go infra libraries
- Go WebDAV implementation
- Finder native WebDAV mount UX
- optional Nextcloud adapter primitives later
### Own
- the betterNAS domain model
- the control-server API
- the node registration and export model
- the mount profile model
- the self-hosted stack wiring
- the repo contract and shared schemas
- the root `pnpm verify` loop
## The next implementation slices
1. make `apps/web` expose the real mount flow to a user
2. add durable control-server storage for nodes, exports, and grants
3. define the self-hosted NAS install shape for `apps/node-agent`
4. keep the optional cloud adapter out of the critical path