init (#5)

docs/05-build-plan.md

@@ -49,7 +49,7 @@ The other three parts are execution surfaces:
 | 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 |
+| Control plane | Go stdlib routing, pgx/sqlc, go-redis/asynq, OpenAPI codegen | 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 |
 
@@ -72,10 +72,11 @@ The NAS node should be boring and reproducible.
 ## 2. Control plane
 
 Start from:
-- the current `exapps/control-plane` scaffold
-- TypeScript
-- Postgres
-- Redis
+- Go
+- standard library routing first
+- Postgres via `pgx` and `sqlc`
+- Redis via `go-redis`
+- OpenAPI-driven contracts
 - standalone API mindset
 
 Do not start by writing:
@@ -151,7 +152,7 @@ This is high leverage, but should not block Phase A.
 - Nix module patterns
 
 ### Control plane
-- current TypeScript repo scaffold
+- Go API service scaffold
 - Postgres
 - Redis
 
@@ -193,7 +194,7 @@ This is high leverage, but should not block Phase A.
 | Part | First scaffold |
 |---|---|
 | NAS node | Nix flake/module + WebDAV server service config |
-| Control plane | current TypeScript control-plane service scaffold |
+| Control plane | Go service + OpenAPI contract + Postgres/Redis adapters later |
 | Local device | documented Finder mount flow, then lightweight helper app |
 | Cloud/web layer | current Nextcloud scaffold and shell app |
 

docs/architecture.md

@@ -74,6 +74,19 @@ Use these in this order:
    - [`docs/04-cloud-web-layer.md`](/home/rathi/Documents/GitHub/betterNAS/docs/04-cloud-web-layer.md)
    - [`docs/05-build-plan.md`](/home/rathi/Documents/GitHub/betterNAS/docs/05-build-plan.md)
 
+## Repo lanes
+
+The monorepo is split into these primary implementation lanes:
+
+- [`apps/node-agent`](/home/rathi/Documents/GitHub/betterNAS/apps/node-agent)
+- [`apps/control-plane`](/home/rathi/Documents/GitHub/betterNAS/apps/control-plane)
+- [`apps/web`](/home/rathi/Documents/GitHub/betterNAS/apps/web)
+- [`apps/nextcloud-app`](/home/rathi/Documents/GitHub/betterNAS/apps/nextcloud-app)
+- [`packages/contracts`](/home/rathi/Documents/GitHub/betterNAS/packages/contracts)
+
+Every parallel task should primarily stay inside one of those lanes unless it is
+an explicit contract task.
+
 ## The contract surface we need first
 
 The first shared contract set should cover only the seams that let all four

docs/references.md

@@ -32,27 +32,57 @@ The goal is simple: do not lose the external pieces that give us leverage.
 
 ## Control plane
 
-### Current scaffold
-
-- current control-plane seed
-  - path: [exapps/control-plane](/home/rathi/Documents/GitHub/betterNAS/exapps/control-plane)
-  - why: existing TypeScript seed for the first real backend
-
 ### Backend and infra references
 
-- Fastify
-  - repo: https://github.com/fastify/fastify
-  - why: likely good fit for a TypeScript API backend
+- Go routing enhancements
+  - docs: https://go.dev/blog/routing-enhancements
+  - why: best low-dependency baseline if we stay with the standard library
+
+- `chi`
+  - repo: https://github.com/go-chi/chi
+  - why: thin stdlib-friendly router if we want middleware and route groups
 
 - PostgreSQL
   - docs: https://www.postgresql.org/docs/
   - why: source of truth for product metadata
 
+- `pgx`
+  - repo: https://github.com/jackc/pgx
+  - why: Postgres-first Go driver and toolkit
+
+- `sqlc`
+  - repo: https://github.com/sqlc-dev/sqlc
+  - why: typed query generation for Go
+
 - Redis
   - docs: https://redis.io/docs/latest/
   - why: cache, jobs, ephemeral coordination
 
-### SSH access / gateway references
+- `go-redis`
+  - repo: https://github.com/redis/go-redis
+  - why: primary Redis client for Go
+
+- `asynq`
+  - repo: https://github.com/hibiken/asynq
+  - why: practical Redis-backed background jobs
+
+- `koanf`
+  - repo: https://github.com/knadh/koanf
+  - why: layered config if the control plane grows beyond env-only config
+
+- `envconfig`
+  - repo: https://github.com/kelseyhightower/envconfig
+  - why: small env-only config loader
+
+- `log/slog`
+  - docs: https://pkg.go.dev/log/slog
+  - why: structured logging without extra dependencies
+
+- `oapi-codegen`
+  - repo: https://github.com/oapi-codegen/oapi-codegen
+  - why: generate Go and TS surfaces from OpenAPI with less drift
+
+### SSH access / gateway reference
 
 - `sshpiper`
   - repo: https://github.com/tg123/sshpiper
@@ -76,6 +106,18 @@ The goal is simple: do not lose the external pieces that give us leverage.
   - docs: https://developer.apple.com/documentation/
   - why: Keychain, launch agents, desktop helpers, future native integration
 
+- Keychain data protection
+  - docs: https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web
+  - why: baseline secret-storage model for device credentials
+
+- Finder Sync extensions
+  - docs: https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/Finder.html
+  - why: future helper-app integration pattern if Finder UX grows
+
+- WebDAV RFC 4918
+  - docs: https://www.rfc-editor.org/rfc/rfc4918
+  - why: protocol semantics and caveats
+
 ## Cloud / web layer
 
 ### Nextcloud server and app references