betterNAS monorepo
++ The repo is organized so each system part can be built in parallel + without inventing new interfaces. The source of truth is the root + contract plus the shared contracts package. +
+{children}
+ + ); +} diff --git a/packages/ui/src/code.tsx b/packages/ui/src/code.tsx new file mode 100644 index 0000000..f7cbd22 --- /dev/null +++ b/packages/ui/src/code.tsx @@ -0,0 +1,11 @@ +import { type JSX } from "react"; + +export function Code({ + children, + className, +}: { + children: React.ReactNode; + className?: string; +}): JSX.Element { + return{children};
+}
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
new file mode 100644
index 0000000..b29f484
--- /dev/null
+++ b/packages/ui/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "@betternas/typescript-config/react-library.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "strictNullChecks": true
+ },
+ "include": ["src"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/scripts/dev-down b/scripts/dev-down
index 99f0a43..ac48825 100755
--- a/scripts/dev-down
+++ b/scripts/dev-down
@@ -3,7 +3,7 @@
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-compose_file="$repo_root/docker/compose.dev.yml"
+compose_file="$repo_root/infra/docker/compose.dev.yml"
args=(down --remove-orphans)
diff --git a/scripts/dev-up b/scripts/dev-up
index c42ad65..6e81a61 100755
--- a/scripts/dev-up
+++ b/scripts/dev-up
@@ -3,8 +3,8 @@
set -euo pipefail
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-compose_file="$repo_root/docker/compose.dev.yml"
-app_source_dir="$repo_root/apps/betternascontrolplane"
+compose_file="$repo_root/infra/docker/compose.dev.yml"
+app_source_dir="$repo_root/apps/nextcloud-app"
nextcloud_occ() {
docker compose -f "$compose_file" exec -T --user www-data --workdir /var/www/html nextcloud php occ "$@"
diff --git a/skeleton.md b/skeleton.md
new file mode 100644
index 0000000..572202c
--- /dev/null
+++ b/skeleton.md
@@ -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
diff --git a/turbo.json b/turbo.json
new file mode 100644
index 0000000..a0c81ed
--- /dev/null
+++ b/turbo.json
@@ -0,0 +1,24 @@
+{
+ "$schema": "https://turborepo.dev/schema.json",
+ "ui": "tui",
+ "tasks": {
+ "build": {
+ "dependsOn": ["^build"],
+ "inputs": ["$TURBO_DEFAULT$", ".env*"],
+ "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+ },
+ "lint": {
+ "dependsOn": ["^lint"]
+ },
+ "check-types": {
+ "dependsOn": ["^check-types"]
+ },
+ "test": {
+ "dependsOn": ["^test"]
+ },
+ "dev": {
+ "cache": false,
+ "persistent": true
+ }
+ }
+}