mirror of
https://github.com/harivansh-afk/betterNAS.git
synced 2026-04-15 09:01:13 +00:00
init (#5)
This commit is contained in:
Hari
GitHub
parent
4f174ec3a8
commit
b68151035a
81 changed files with 6263 additions and 545 deletions
263
skeleton.md
Normal file
263
skeleton.md
Normal file
|
|
@ -0,0 +1,263 @@
|
|||
# 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
|
||||
- give agents a safe place to work in parallel
|
||||
- keep the list of upstream references we are stealing from
|
||||
|
||||
## Repo shape
|
||||
|
||||
```text
|
||||
betterNAS/
|
||||
├── apps/
|
||||
│ ├── web/ # Next.js control-plane UI
|
||||
│ ├── control-plane/ # Go control-plane API
|
||||
│ ├── node-agent/ # Go NAS runtime + WebDAV surface
|
||||
│ └── nextcloud-app/ # optional Nextcloud adapter
|
||||
├── packages/
|
||||
│ ├── contracts/ # canonical OpenAPI, schemas, TS types
|
||||
│ ├── sdk-ts/ # TS SDK facade for the web app
|
||||
│ ├── ui/ # shared React UI
|
||||
│ ├── eslint-config/ # shared lint config
|
||||
│ └── typescript-config/ # shared TS config
|
||||
├── infra/
|
||||
│ └── docker/ # local runtime stack
|
||||
├── docs/ # architecture and part docs
|
||||
├── scripts/ # local helper scripts
|
||||
├── 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 | best UI velocity, best admin/control-plane UX |
|
||||
| `apps/control-plane` | Go | strong concurrency, static binaries, operationally simple |
|
||||
| `apps/node-agent` | Go | best fit for host runtime, WebDAV service, and future Nix deployment |
|
||||
| `apps/nextcloud-app` | PHP | native language for the Nextcloud adapter surface |
|
||||
| `packages/contracts` | OpenAPI + JSON Schema + TypeScript | language-neutral source of truth with practical TS ergonomics |
|
||||
| `packages/sdk-ts` | TypeScript | ergonomic consumption from the Next.js app |
|
||||
|
||||
## Canonical contract rule
|
||||
|
||||
The source of truth for shared interfaces is:
|
||||
|
||||
1. [`docs/architecture.md`](/home/rathi/Documents/GitHub/betterNAS/docs/architecture.md)
|
||||
2. [`packages/contracts/openapi/betternas.v1.yaml`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/openapi/betternas.v1.yaml)
|
||||
3. [`packages/contracts/schemas`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/schemas)
|
||||
4. [`packages/contracts/src`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts/src)
|
||||
|
||||
Agents must not invent private shared request or response shapes outside those
|
||||
locations.
|
||||
|
||||
## Parallel lanes
|
||||
|
||||
```text
|
||||
shared write surface
|
||||
+-------------------------------------------+
|
||||
| docs/architecture.md |
|
||||
| packages/contracts/ |
|
||||
+----------------+--------------------------+
|
||||
|
|
||||
+-----------------+-----------------+-----------------+
|
||||
| | | |
|
||||
v v v v
|
||||
NAS node control plane local device cloud layer
|
||||
lane lane lane lane
|
||||
```
|
||||
|
||||
Allowed ownership:
|
||||
|
||||
- NAS node lane
|
||||
- `apps/node-agent`
|
||||
- future `infra/nix/node-*`
|
||||
- control-plane lane
|
||||
- `apps/control-plane`
|
||||
- DB and queue integration code later
|
||||
- local-device lane
|
||||
- mount docs first
|
||||
- future helper app
|
||||
- cloud layer lane
|
||||
- `apps/nextcloud-app`
|
||||
- Nextcloud mapping logic
|
||||
- shared contract lane
|
||||
- `packages/contracts`
|
||||
- `packages/sdk-ts`
|
||||
- `docs/architecture.md`
|
||||
|
||||
## The first verification loop
|
||||
|
||||
```text
|
||||
[node-agent]
|
||||
serves WebDAV export
|
||||
|
|
||||
v
|
||||
[control-plane]
|
||||
registers node + export
|
||||
issues mount profile
|
||||
|
|
||||
v
|
||||
[local device]
|
||||
mounts WebDAV in Finder
|
||||
|
|
||||
v
|
||||
[cloud layer]
|
||||
optionally exposes same export in Nextcloud
|
||||
```
|
||||
|
||||
If a task does not make one of those steps more real, it is probably too early.
|
||||
|
||||
## 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/BFF, not the system-of-record backend
|
||||
|
||||
### Go control plane
|
||||
|
||||
- Go routing enhancements
|
||||
- https://go.dev/blog/routing-enhancements
|
||||
- why: stdlib-first routing baseline
|
||||
|
||||
- `chi`
|
||||
- https://github.com/go-chi/chi
|
||||
- why: minimal router if stdlib patterns become too bare
|
||||
|
||||
- `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
|
||||
|
||||
- `koanf`
|
||||
- https://github.com/knadh/koanf
|
||||
- why: layered config if env-only config becomes too small
|
||||
|
||||
- `envconfig`
|
||||
- https://github.com/kelseyhightower/envconfig
|
||||
- why: tiny env-only config option
|
||||
|
||||
- `log/slog`
|
||||
- https://pkg.go.dev/log/slog
|
||||
- why: structured logging without adding a logging framework first
|
||||
|
||||
- `oapi-codegen`
|
||||
- https://github.com/oapi-codegen/oapi-codegen
|
||||
- why: generate Go and TS surfaces from OpenAPI
|
||||
|
||||
### NAS node 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
|
||||
|
||||
- Nixpkgs
|
||||
- https://github.com/NixOS/nixpkgs
|
||||
- why: service module and packaging reference
|
||||
|
||||
### Local device and 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
|
||||
|
||||
- Finder Sync extensions
|
||||
- https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/Finder.html
|
||||
- why: future helper app / Finder integration reference
|
||||
|
||||
- WebDAV RFC 4918
|
||||
- https://www.rfc-editor.org/rfc/rfc4918
|
||||
- why: protocol semantics and edge cases
|
||||
|
||||
### Cloud and adapter layer
|
||||
|
||||
- Nextcloud app template
|
||||
- https://github.com/nextcloud/app_template
|
||||
- why: thin adapter app reference
|
||||
|
||||
- AppAPI / External Apps
|
||||
- https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html
|
||||
- why: official external-app integration path
|
||||
|
||||
- Nextcloud WebDAV docs
|
||||
- https://docs.nextcloud.com/server/latest/user_manual/en/files/access_webdav.html
|
||||
- why: protocol/client behavior reference
|
||||
|
||||
- Nextcloud external storage
|
||||
- https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/external_storage_configuration_gui.html
|
||||
- why: storage aggregation behavior
|
||||
|
||||
- Nextcloud file sharing config
|
||||
- https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/file_sharing_configuration.html
|
||||
- why: share semantics 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
|
||||
- Nextcloud shell-app and cloud/web primitives
|
||||
|
||||
### Own
|
||||
|
||||
- the betterNAS domain model
|
||||
- the control-plane API
|
||||
- the node registration and export model
|
||||
- the mount profile model
|
||||
- the mapping between cloud mode and mount mode
|
||||
- the repo contract and shared schemas
|
||||
|
||||
## The first implementation slices after this scaffold
|
||||
|
||||
1. make `apps/node-agent` serve a real configurable WebDAV export
|
||||
2. make `apps/control-plane` store real node/export records
|
||||
3. issue real mount profiles from the control plane
|
||||
4. make `apps/web` let a user pick an export and request a profile
|
||||
5. keep `apps/nextcloud-app` thin and optional
|
||||
Loading…
Add table
Add a link
Reference in a new issue