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

docs

Browse source
This commit is contained in:
Harivansh Rathi 2026-04-01 01:03:21 +00:00
parent 7ae2b7a71c
commit a4cb20d228
9 changed files with 596 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

0
docs/architecture.md → docs/current-architecture.md
View file

209
docs/platform-foundation.md Normal file
View file

@ -0,0 +1,209 @@
# aiNAS Platform Foundation
This document is the north-star planning artifact for the next phase of aiNAS.
The scaffold phase is done. We now have a verified local Nextcloud runtime, a thin Nextcloud shell app, and a minimal aiNAS control-plane service. The next phase is about deciding what we will steal from Nextcloud, what we will own ourselves, and how the product should evolve without turning Nextcloud into the center of the system.
## Product Stance
aiNAS is not "a custom Nextcloud theme."
aiNAS is a storage control plane with:
- its own product semantics
- its own API
- its own web surface
- its own future device and mount model
Nextcloud remains valuable, but it is an upstream substrate and reference implementation, not the long-term system of record for the product.
## High-Level Model
```text
aiNAS platform model
users / browser / desktop / mobile / cli
|
v
+--------------------------+
| aiNAS control plane |
|--------------------------|
| identity |
| workspaces |
| devices |
| storage sources |
| shares |
| mount profiles |
| policies |
| audit + jobs |
+------------+-------------+
|
+--------------+---------------+
| |
v v
+----------------------+ +------------------------+
| Nextcloud adapter | | device access layer |
|----------------------| |------------------------|
| files/share/web UI | | desktop / mobile / cli |
| external storage | | native mount/sync |
| webdav / user shell | | device orchestration |
+----------+-----------+ +-----------+------------+
| |
+---------------+--------------+
|
v
+-------------------------+
| storage backends |
| SMB NFS S3 WebDAV Local |
+-------------------------+
```
## What We Steal From Nextcloud
We should deliberately reuse as much as possible before building our own equivalents.
### Server-side primitives
Nextcloud is a strong source of reusable server-side primitives:
- external storage support for Amazon S3, FTP/FTPS, Local, Nextcloud, OpenStack Object Storage, SFTP, SMB/CIFS, and WebDAV
- web file UI and sharing UI
- WebDAV and OCS/external API surfaces
- built-in user/session/admin runtime
- branding and theming hooks
- custom app shell inside the main web experience
### Client-side references
Nextcloud is also a strong source of reference implementations:
- desktop client for macOS and other desktop platforms
- macOS Virtual Files / Finder integration
- iOS app
The desktop client is especially high leverage because the official docs describe it as appearing as a dedicated location in the Finder sidebar, with offline controls, file previews, sharing, server-side actions, and automatic change detection.
## What aiNAS Must Own
Even with heavy reuse, the product still needs its own control plane.
aiNAS should own:
- the domain model for users, devices, workspaces, storage sources, shares, policies, and mount profiles
- the product API used by future web, desktop, and mobile surfaces
- device and mount orchestration semantics
- product-specific RBAC and policy logic
- audit and operational workflows
Nextcloud should not become the system of record for those concerns.
## Recommended Technical Shape
### 1. Control plane
Start with one modular service, not many microservices.
Recommended stack:
- TypeScript for the control-plane API
- Postgres for product metadata
- Redis for cache and background work
Why:
- the repo already uses TypeScript for contracts and the initial control-plane service
- a modular monolith keeps boundaries explicit without premature service sprawl
- Postgres and Redis fit the operational model well
### 2. Web product
Build a standalone control-plane web app outside Nextcloud.
Recommended stack:
- Next.js
Why:
- it pairs well with a TypeScript backend
- it gives us a real product web surface instead of living forever inside the Nextcloud shell
- the Nextcloud app can remain a thin adapter and optional embedded surface
### 3. Device layer
Treat device-native mounts and sync as a separate concern from the control plane.
Recommended direction:
- defer a custom device agent until we know we need true mount orchestration
- when we do need one, prefer Go for the first device-side daemon
Why:
- Finder-style cloud-drive presence can be heavily referenced from Nextcloud desktop first
- true mount-at-login behavior is a different product problem and likely needs its own agent
## Product Modes
There are two product shapes hidden inside the idea. We should be explicit about them.
### Mode A: cloud-drive style
Characteristics:
- Finder presence
- virtual files / files-on-demand
- sync-like behavior
- lower custom device work
This mode aligns well with Nextcloud desktop and should be the first reference path.
### Mode B: true remote mount
Characteristics:
- explicit filesystem mount
- login-time mount orchestration
- stronger native OS coupling
- more custom device-side work
This mode should be treated as a later capability unless it becomes the immediate core differentiator.
## System of Record
The working assumption for the next phase is:
- aiNAS is the system of record for product semantics
- Nextcloud is the upstream file/share/storage substrate
This keeps the architecture clean and avoids accidentally letting the adapter become the product.
## Recommended Delivery Sequence
1. Define the Nextcloud substrate we are officially adopting.
2. Define the aiNAS control-plane domain model and API.
3. Build the first real control-plane backend around Postgres and Redis.
4. Build a standalone Next.js control-plane web app.
5. Deepen the Nextcloud adapter so it mirrors aiNAS-owned semantics.
6. Only then decide how much custom device and mount orchestration we need.
## Decision Matrix
| Area | Use Nextcloud first | Own in aiNAS |
|---|---|---|
| file and sharing web UX | yes | later, only if needed |
| storage backend aggregation | yes | overlay policy, source catalog, and orchestration |
| macOS Finder-style cloud presence | yes, reference desktop client first | later, if branded/native client is required |
| iOS app | yes, reference Nextcloud iOS first | later, if branded/native client is required |
| product API | no | yes |
| device model | no | yes |
| mount model | no | yes |
| policy / RBAC semantics | baseline from Nextcloud is acceptable | real product semantics belong in aiNAS |
| admin/control UI | partial in Nextcloud | full standalone control plane should be ours |
## Open Questions
These questions should be explicitly resolved in the next planning change:
- Is v1 cloud-drive-first, mount-first, or hybrid?
- Which storage backends are in scope first: SMB, S3, WebDAV, local, or all of them?
- What should aiNAS identity own in v1 versus what should be delegated to Nextcloud users/groups?
- Should Nextcloud remain part of the end-user workflow in v1, or mostly act as a backend adapter?
- When do we fork or brand the desktop and mobile clients, if ever?
## Reference Sources
- Nextcloud AppAPI / ExApps
- Nextcloud external storage administration docs
- Nextcloud external API / OCS docs
- Nextcloud theming and branded client links
- Nextcloud macOS Virtual Files docs
- public Nextcloud desktop and iOS repositories

233
openspec/changes/define-platform-foundation/design.md Normal file
View file

@ -0,0 +1,233 @@
## Context
aiNAS now has a verified local scaffold:
- a stock Nextcloud runtime
- a thin aiNAS app inside Nextcloud
- a minimal aiNAS control-plane service
- shared contracts
That scaffold proves the direction, but it does not yet answer the more important product questions. We need to decide what the actual backend is, what should remain delegated to Nextcloud, how the standalone product should take shape, and which work has the highest leverage.
The user goal is clear: build "file storage everywhere" with native-feeling access on devices, a strong web UX, sharing and RBAC, and room to rewrite product logic freely over time. The design therefore needs to preserve leverage from Nextcloud without letting it become the center of the product.
## Goals / Non-Goals
**Goals**
- Define which primitives we will adopt from Nextcloud versus own ourselves.
- Define the aiNAS control plane as the long-term system of record for product semantics.
- Define the first real backend domain at a high level.
- Define the first standalone web product direction outside Nextcloud.
- Define how device-native access fits into the architecture without forcing premature implementation.
**Non-Goals**
- Implement the backend or web UI in this change.
- Finalize every database field or endpoint shape.
- Decide final distribution details for desktop or mobile clients.
- Commit to a microservice topology.
## Core Decisions
### 1. aiNAS owns product semantics
aiNAS should be the system of record for:
- workspaces
- devices
- storage sources
- shares as product objects
- mount profiles
- policy and RBAC semantics
- audit and orchestration flows
Nextcloud should not become the long-term system of record for those concepts.
Rationale:
- keeps product evolution independent from the Nextcloud monolith
- supports future standalone clients and surfaces
- makes the Nextcloud adapter replaceable over time
### 2. Nextcloud remains an upstream substrate
Nextcloud is valuable because it already provides:
- external storage support for multiple backend types
- a strong web file and sharing surface
- WebDAV and OCS APIs
- a desktop client with Finder integration
- a mobile app
aiNAS should deliberately reuse those primitives where they reduce time-to-product, while keeping product-specific logic outside of Nextcloud.
Rationale:
- highest leverage path
- strongest reference implementations
- avoids rebuilding low-differentiation components too early
### 3. The control plane should remain a standalone aiNAS service
The current ExApp-compatible service is useful, but the long-term shape should be a standalone aiNAS backend that happens to have a Nextcloud adapter, not a backend that is conceptually trapped inside the AppAPI/ExApp model.
Rationale:
- the control plane should be reusable by future standalone clients
- aiNAS will likely want richer event, device, and auth flows than a pure Nextcloud extension mindset encourages
- keeping the service standalone reduces accidental architectural lock-in
### 4. Start with one modular backend service
Do not split into many services yet.
The first real backend should be a modular monolith with internal modules for:
- identity
- devices
- workspaces
- storage sources
- shares
- policies
- mount profiles
- audit/jobs
Rationale:
- keeps implementation velocity high
- preserves clear boundaries without creating distributed-system overhead
- still allows future extraction if needed
### 5. Prefer TypeScript for the first real control plane
Recommended stack:
- TypeScript backend
- Postgres for persistent product metadata
- Redis for ephemeral state and jobs
- Next.js for the standalone web surface
Rationale:
- matches the current repo direction
- minimizes coordination cost between API, contracts, and web
- keeps the first implementation path simple
### 6. Treat device-native mount orchestration as a separate later concern
There are two different product modes:
```text
Mode A: cloud-drive style
- Finder sidebar presence
- virtual files / file-provider behavior
- lower custom device work
Mode B: true remote mount
- explicit mounted filesystem
- login-time mount orchestration
- stronger device-native behavior
- more custom agent work
```
The design should keep both modes possible, but the first backend and web planning should not depend on solving Mode B immediately.
Rationale:
- Nextcloud already gives a stronger starting point for Mode A
- Mode B likely requires a custom agent and more device-specific work
## High-Level Architecture
```text
aiNAS target architecture
browser / desktop / mobile / cli
|
v
+---------------------------+
| aiNAS control plane |
|---------------------------|
| identity + sessions |
| workspaces |
| devices |
| storage sources |
| shares |
| mount profiles |
| policies |
| audit + jobs |
+-------------+-------------+
|
+----------------+----------------+
| |
v v
+------------------------+ +-------------------------+
| Nextcloud adapter | | device access layer |
|------------------------| |-------------------------|
| files / sharing / UI | | sync / mount behavior |
| external storage | | desktop/mobile helpers |
| webdav / OCS surfaces | | future native agent |
+-----------+------------+ +------------+------------+
| |
+----------------+----------------+
|
v
+-------------------------+
| storage backends |
| SMB NFS S3 WebDAV Local |
+-------------------------+
```
## High-Level Domain Contracts
The first control-plane design should center on these entities:
- `User`
- `Workspace`
- `Device`
- `StorageSource`
- `Share`
- `MountProfile`
- `Policy`
- `AuditEvent`
Relationship sketch:
```text
User
|
+-- Device
|
+-- Workspace
|
+-- StorageSource
+-- Share
+-- MountProfile
+-- Policy
+-- AuditEvent
```
The first API categories should likely map to those entities:
- `/api/me`
- `/api/workspaces`
- `/api/storage-sources`
- `/api/shares`
- `/api/devices`
- `/api/mount-profiles`
- `/api/policies`
This is intentionally high level. The exact path layout, auth model, and payload schema should be refined in later implementation changes.
## Risks / Trade-offs
- If we let Nextcloud users/groups become the permanent product identity model, aiNAS will be harder to evolve independently.
- If we overbuild the control plane before deciding which Nextcloud primitives we are actually keeping, we may duplicate useful substrate capabilities unnecessarily.
- If we force a custom device agent too early, we may spend time on native integration before proving the backend and product semantics.
- If we defer too much ownership to Nextcloud, the product may never fully become aiNAS.
## Sequencing
Recommended change sequence:
1. Define the Nextcloud substrate we are officially adopting.
2. Define the control-plane core domain and high-level API.
3. Build the first real control-plane backend around Postgres and Redis.
4. Build the standalone Next.js control-plane web surface.
5. Deepen the Nextcloud adapter.
6. Decide how much custom device access and mount logic is needed for v1 and v2.
## Open Questions
- Is v1 cloud-drive-first, mount-first, or explicitly hybrid?
- Which storage backends are in scope first?
- How much identity should be delegated to Nextcloud in v1?
- Should end users interact directly with Nextcloud in v1, or mostly through aiNAS surfaces?
- When, if ever, should the desktop or mobile clients be branded or forked?

29
openspec/changes/define-platform-foundation/proposal.md Normal file
View file

@ -0,0 +1,29 @@
## Why
The scaffold phase is complete, but the repo still lacks a clear product-level plan for how aiNAS should evolve beyond a thin Nextcloud shell and a minimal backend stub. Before implementing more code, we need planning artifacts that define the system of record, the role Nextcloud should play, the control-plane domain we intend to own, and the delivery sequence for the first real product capabilities.
## What Changes
- Add a north-star planning layer for the aiNAS platform.
- Define the Nextcloud substrate that aiNAS will adopt instead of rebuilding from scratch.
- Define the first high-level control-plane domain model and service contracts.
- Define the intended standalone web control-plane direction outside Nextcloud.
- Define the future device access layer boundary, including the distinction between cloud-drive style access and true remote mounts.
## Capabilities
### New Capabilities
- `nextcloud-substrate`: A documented contract for which server, storage, sharing, and client primitives aiNAS will adopt from Nextcloud.
- `control-plane-core`: A documented contract for the first real aiNAS backend domain model and API surface.
- `standalone-control-plane-web`: A documented contract for the future Next.js web console that will become the aiNAS product surface outside Nextcloud.
- `device-access-layer`: A documented contract for how aiNAS will eventually support native device access, including mount and sync modes.
### Modified Capabilities
- None.
## Impact
- Affected code: planning artifacts only
- Affected systems: architecture, product sequencing, service boundaries, implementation roadmap
- Dependencies: Nextcloud server, Nextcloud desktop/iOS references, aiNAS control-plane service, future Postgres/Redis-backed product metadata
- APIs: establishes the intended aiNAS-owned API and adapter boundaries at a high level before implementation

29
openspec/changes/define-platform-foundation/specs/control-plane-core/spec.md Normal file
View file

@ -0,0 +1,29 @@
## ADDED Requirements
### Requirement: aiNAS control plane as product system of record
The system SHALL define an aiNAS-owned control plane as the authoritative home for product-level domain concepts.
#### Scenario: Product semantics require persistence
- **WHEN** aiNAS needs to represent devices, workspaces, storage sources, shares, mount profiles, policies, or audit history
- **THEN** the planning artifacts MUST place those concepts inside the aiNAS control-plane domain model
### Requirement: High-level domain contracts
The platform SHALL define a first high-level contract map for core entities and API categories before implementation proceeds.
#### Scenario: Future implementation work needs a stable conceptual frame
- **WHEN** engineers start implementing the control plane
- **THEN** the planning artifacts MUST already identify the first core entities and the first API categories those entities imply
### Requirement: Standalone service posture
The control plane SHALL remain architecturally standalone even if it is temporarily packaged or surfaced through Nextcloud-compatible mechanisms.
#### Scenario: aiNAS backend is consumed by multiple surfaces
- **WHEN** a standalone web app, Nextcloud shell, or future device client needs backend behavior
- **THEN** the design MUST treat the control plane as a reusable aiNAS service rather than as logic conceptually trapped inside the Nextcloud app model
### Requirement: Single modular backend first
The platform SHALL prefer one modular backend service before splitting the control plane into multiple distributed services.
#### Scenario: Engineers plan service topology
- **WHEN** the first real control-plane backend is planned
- **THEN** the default architecture MUST be one service with explicit internal modules rather than many microservices

22
openspec/changes/define-platform-foundation/specs/device-access-layer/spec.md Normal file
View file

@ -0,0 +1,22 @@
## ADDED Requirements
### Requirement: Distinguish cloud-drive access from true remote mounts
The platform SHALL explicitly distinguish between cloud-drive style access and true remote mount behavior.
#### Scenario: Device access strategy is discussed
- **WHEN** aiNAS plans device-native access on macOS or mobile
- **THEN** the planning artifacts MUST state whether the capability is based on cloud-drive style client behavior, true remote mounts, or both
### Requirement: Defer custom native agent work until justified
The platform SHALL not require a custom device-native agent for the first backend and control-plane planning unless true remote mount orchestration is confirmed as a near-term requirement.
#### Scenario: Delivery sequencing is chosen
- **WHEN** implementation order is planned
- **THEN** the design MUST allow heavy reuse of Nextcloud client references before requiring a custom native device daemon
### Requirement: Keep future device agent possible
The architecture SHALL preserve a clear boundary where a future aiNAS-owned device access layer can be introduced without rewriting the control plane.
#### Scenario: Product later adds login-time mounts or stronger native behavior
- **WHEN** aiNAS decides to add explicit mount orchestration or device-native workflows
- **THEN** the design MUST place that behavior in a device access layer separate from the core control-plane domain

29
openspec/changes/define-platform-foundation/specs/nextcloud-substrate/spec.md Normal file
View file

@ -0,0 +1,29 @@
## ADDED Requirements
### Requirement: Nextcloud substrate boundary
The system SHALL explicitly define which storage, sharing, and client primitives aiNAS adopts from Nextcloud and which concerns remain aiNAS-owned.
#### Scenario: Product planning references Nextcloud capabilities
- **WHEN** aiNAS decides whether to build or reuse a capability
- **THEN** the planning artifacts MUST classify the capability as either Nextcloud substrate, aiNAS-owned logic, or a later optional fork/reference path
### Requirement: Reuse external storage backends
The platform SHALL treat Nextcloud external storage support as the first candidate substrate for connecting backend storage systems.
#### Scenario: aiNAS selects initial backend storage types
- **WHEN** aiNAS chooses the first storage backends to support
- **THEN** the plan MUST assume reuse of Nextcloud-supported external storage backends before proposing custom storage ingestion infrastructure
### Requirement: Reuse desktop and mobile references first
The platform SHALL treat the public Nextcloud desktop and iOS clients as the first reference implementations for cloud-drive style access before planning fully custom clients.
#### Scenario: aiNAS evaluates native device access
- **WHEN** the product needs Finder-style or mobile file access
- **THEN** the plan MUST document whether Nextcloud clients are being used directly, referenced, branded later, or intentionally replaced
### Requirement: Keep Nextcloud as substrate, not system of record
The platform SHALL not let Nextcloud become the long-term system of record for aiNAS-specific product semantics.
#### Scenario: New product concept is introduced
- **WHEN** aiNAS introduces workspaces, devices, policies, mount profiles, or similar product concepts
- **THEN** the design MUST model those concepts in aiNAS-owned contracts rather than relying on implicit Nextcloud-only representations

22
openspec/changes/define-platform-foundation/specs/standalone-control-plane-web/spec.md Normal file
View file

@ -0,0 +1,22 @@
## ADDED Requirements
### Requirement: Standalone aiNAS web surface
The platform SHALL plan for a standalone web control-plane surface outside Nextcloud.
#### Scenario: Product UI expands beyond an embedded shell
- **WHEN** aiNAS needs an admin or product control interface that is larger than a thin Nextcloud page
- **THEN** the plan MUST place that interface in an aiNAS-owned standalone web application
### Requirement: Web UI consumes aiNAS API
The standalone web application SHALL be designed to consume aiNAS-owned backend contracts rather than Nextcloud internals directly.
#### Scenario: Web product feature requires backend data
- **WHEN** the standalone web surface needs workspaces, devices, shares, or policies
- **THEN** it MUST obtain those concepts through the aiNAS control-plane API design rather than by binding directly to Nextcloud internal models
### Requirement: Preserve Nextcloud shell as adapter
The presence of a standalone web app SHALL not remove the need for the thin Nextcloud shell as an adapter and embedded entry surface.
#### Scenario: aiNAS still needs a presence inside Nextcloud
- **WHEN** the broader product grows outside the Nextcloud UI
- **THEN** the shell app MUST remain conceptually limited to integration and entry-point responsibilities rather than absorbing the full standalone product

23
openspec/changes/define-platform-foundation/tasks.md Normal file
View file

@ -0,0 +1,23 @@
## 1. Planning and boundary definition
- [ ] 1.1 Review the new planning artifacts and resolve the remaining open questions around v1 product mode, identity ownership, and first storage backends
- [ ] 1.2 Confirm the official Nextcloud primitives aiNAS will adopt in v1 and which ones are only reference implementations
- [ ] 1.3 Confirm the control plane as the system of record for product semantics
## 2. Control-plane architecture planning
- [ ] 2.1 Refine the first control-plane entity model for users, workspaces, devices, storage sources, shares, mount profiles, policies, and audit events
- [ ] 2.2 Define the first high-level API categories and authentication assumptions for the standalone control plane
- [ ] 2.3 Choose the initial implementation stack for the real control plane, including TypeScript backend, Postgres, Redis, and the standalone web stack
## 3. Product surface planning
- [ ] 3.1 Define the role of the standalone Next.js control-plane web app versus the embedded Nextcloud shell
- [ ] 3.2 Define the v1 desktop and mobile posture: direct reuse, branded later, or fully custom
- [ ] 3.3 Decide whether true remote mounts are a v1 requirement or a later device-layer capability
## 4. Follow-on implementation changes
- [ ] 4.1 Propose the next implementation change for defining the Nextcloud substrate in concrete runtime terms
- [ ] 4.2 Propose the implementation change for the first real aiNAS control-plane backend
- [ ] 4.3 Propose the implementation change for the standalone control-plane web UI