This commit is contained in:
Harivansh Rathi 2026-04-01 02:28:45 +00:00
parent 12c53f3515
commit dc7969e579
37 changed files with 177 additions and 177 deletions

View file

@ -1,9 +1,9 @@
## Context
aiNAS now has a verified local scaffold:
betternas now has a verified local scaffold:
- a stock Nextcloud runtime
- a thin aiNAS app inside Nextcloud
- a minimal aiNAS control-plane service
- a thin betternas app inside Nextcloud
- a minimal betternas 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.
@ -14,7 +14,7 @@ The user goal is clear: build "file storage everywhere" with native-feeling acce
**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 betternas 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.
@ -27,9 +27,9 @@ The user goal is clear: build "file storage everywhere" with native-feeling acce
## Core Decisions
### 1. aiNAS owns product semantics
### 1. betternas owns product semantics
aiNAS should be the system of record for:
betternas should be the system of record for:
- workspaces
- devices
- storage sources
@ -54,20 +54,20 @@ Nextcloud is valuable because it already provides:
- 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.
betternas 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
### 3. The control plane should remain a standalone betternas 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.
The current ExApp-compatible service is useful, but the long-term shape should be a standalone betternas 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
- betternas 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
@ -128,13 +128,13 @@ Rationale:
## High-Level Architecture
```text
aiNAS target architecture
betternas target architecture
browser / desktop / mobile / cli
|
v
+---------------------------+
| aiNAS control plane |
| betternas control plane |
|---------------------------|
| identity + sessions |
| workspaces |
@ -208,10 +208,10 @@ This is intentionally high level. The exact path layout, auth model, and payload
## Risks / Trade-offs
- If we let Nextcloud users/groups become the permanent product identity model, aiNAS will be harder to evolve independently.
- If we let Nextcloud users/groups become the permanent product identity model, betternas 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.
- If we defer too much ownership to Nextcloud, the product may never fully become betternas.
## Sequencing
@ -229,5 +229,5 @@ Recommended change sequence:
- 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?
- Should end users interact directly with Nextcloud in v1, or mostly through betternas surfaces?
- When, if ever, should the desktop or mobile clients be branded or forked?

View file

@ -1,11 +1,11 @@
## 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.
The scaffold phase is complete, but the repo still lacks a clear product-level plan for how betternas 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.
- Add a north-star planning layer for the betternas platform.
- Define the Nextcloud substrate that betternas 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.
@ -13,10 +13,10 @@ The scaffold phase is complete, but the repo still lacks a clear product-level p
## 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.
- `nextcloud-substrate`: A documented contract for which server, storage, sharing, and client primitives betternas will adopt from Nextcloud.
- `control-plane-core`: A documented contract for the first real betternas backend domain model and API surface.
- `standalone-control-plane-web`: A documented contract for the future Next.js web console that will become the betternas product surface outside Nextcloud.
- `device-access-layer`: A documented contract for how betternas will eventually support native device access, including mount and sync modes.
### Modified Capabilities
- None.
@ -25,5 +25,5 @@ The scaffold phase is complete, but the repo still lacks a clear product-level p
- 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
- Dependencies: Nextcloud server, Nextcloud desktop/iOS references, betternas control-plane service, future Postgres/Redis-backed product metadata
- APIs: establishes the intended betternas-owned API and adapter boundaries at a high level before implementation

View file

@ -1,11 +1,11 @@
## 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.
### Requirement: betternas control plane as product system of record
The system SHALL define an betternas-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
- **WHEN** betternas needs to represent devices, workspaces, storage sources, shares, mount profiles, policies, or audit history
- **THEN** the planning artifacts MUST place those concepts inside the betternas 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.
@ -17,9 +17,9 @@ The platform SHALL define a first high-level contract map for core entities and
### 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
#### Scenario: betternas 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
- **THEN** the design MUST treat the control plane as a reusable betternas 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.

View file

@ -4,7 +4,7 @@
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
- **WHEN** betternas 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
@ -15,8 +15,8 @@ The platform SHALL not require a custom device-native agent for the first backen
- **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.
The architecture SHALL preserve a clear boundary where a future betternas-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
- **WHEN** betternas 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

View file

@ -1,29 +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.
The system SHALL explicitly define which storage, sharing, and client primitives betternas adopts from Nextcloud and which concerns remain betternas-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
- **WHEN** betternas decides whether to build or reuse a capability
- **THEN** the planning artifacts MUST classify the capability as either Nextcloud substrate, betternas-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
#### Scenario: betternas selects initial backend storage types
- **WHEN** betternas 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
#### Scenario: betternas 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.
The platform SHALL not let Nextcloud become the long-term system of record for betternas-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
- **WHEN** betternas introduces workspaces, devices, policies, mount profiles, or similar product concepts
- **THEN** the design MUST model those concepts in betternas-owned contracts rather than relying on implicit Nextcloud-only representations

View file

@ -1,22 +1,22 @@
## ADDED Requirements
### Requirement: Standalone aiNAS web surface
### Requirement: Standalone betternas 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
- **WHEN** betternas needs an admin or product control interface that is larger than a thin Nextcloud page
- **THEN** the plan MUST place that interface in an betternas-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.
### Requirement: Web UI consumes betternas API
The standalone web application SHALL be designed to consume betternas-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
- **THEN** it MUST obtain those concepts through the betternas 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
#### Scenario: betternas 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

View file

@ -1,7 +1,7 @@
## 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.2 Confirm the official Nextcloud primitives betternas 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
@ -19,5 +19,5 @@
## 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.2 Propose the implementation change for the first real betternas control-plane backend
- [ ] 4.3 Propose the implementation change for the standalone control-plane web UI

View file

@ -1,16 +1,16 @@
## Context
aiNAS is starting as a greenfield project with a clear product boundary: we want our own storage control plane, product UX, and business logic while using Nextcloud as an upstream backend for file storage, sync primitives, sharing primitives, and existing client compatibility. The repository is effectively empty today, so this change needs to establish both the architectural stance and the initial developer scaffold.
betternas is starting as a greenfield project with a clear product boundary: we want our own storage control plane, product UX, and business logic while using Nextcloud as an upstream backend for file storage, sync primitives, sharing primitives, and existing client compatibility. The repository is effectively empty today, so this change needs to establish both the architectural stance and the initial developer scaffold.
The main constraint is maintenance ownership. Forking `nextcloud/server` would move security patches, upstream upgrade churn, and internal compatibility risk onto aiNAS too early. At the same time, pushing all product logic into a traditional Nextcloud app would make our business rules hard to evolve and tightly couple the product to the PHP monolith. The design therefore needs to leave us with a thin in-Nextcloud surface and a separate aiNAS-owned service layer.
The main constraint is maintenance ownership. Forking `nextcloud/server` would move security patches, upstream upgrade churn, and internal compatibility risk onto betternas too early. At the same time, pushing all product logic into a traditional Nextcloud app would make our business rules hard to evolve and tightly couple the product to the PHP monolith. The design therefore needs to leave us with a thin in-Nextcloud surface and a separate betternas-owned service layer.
## Goals / Non-Goals
**Goals:**
- Create a repository scaffold that supports local development with vanilla Nextcloud and aiNAS-owned services.
- Create a repository scaffold that supports local development with vanilla Nextcloud and betternas-owned services.
- Define a thin Nextcloud shell app that handles navigation, branded entry points, and backend integration hooks.
- Define an aiNAS control-plane service boundary for business logic, policy, and orchestration.
- Keep interfaces typed and explicit so future web, desktop, and iOS clients can target aiNAS services rather than Nextcloud internals.
- Define an betternas control-plane service boundary for business logic, policy, and orchestration.
- Keep interfaces typed and explicit so future web, desktop, and iOS clients can target betternas services rather than Nextcloud internals.
- Make the initial architecture easy to extend without forcing a Nextcloud core fork.
**Non-Goals:**
@ -23,7 +23,7 @@ The main constraint is maintenance ownership. Forking `nextcloud/server` would m
### 1. Use vanilla Nextcloud as an upstream backend, not a fork
aiNAS will run a stock Nextcloud instance in local development and future environments. We will extend it through a dedicated aiNAS app and service integrations instead of modifying core server code.
betternas will run a stock Nextcloud instance in local development and future environments. We will extend it through a dedicated betternas app and service integrations instead of modifying core server code.
Rationale:
- Keeps upstream upgrades and security patches tractable.
@ -36,7 +36,7 @@ Alternatives considered:
### 2. Keep the Nextcloud app thin and treat it as an adapter shell
The generated Nextcloud app will own aiNAS-specific UI entry points inside Nextcloud, settings pages, and integration hooks, but SHALL not become the home of core business logic. It will call aiNAS-owned APIs/services for control-plane decisions.
The generated Nextcloud app will own betternas-specific UI entry points inside Nextcloud, settings pages, and integration hooks, but SHALL not become the home of core business logic. It will call betternas-owned APIs/services for control-plane decisions.
Rationale:
- Keeps PHP app code small and replaceable.
@ -46,12 +46,12 @@ Rationale:
Alternatives considered:
- Put most logic directly in the app: rejected because it couples product evolution to the monolith.
### 3. Scaffold an aiNAS control-plane service from the start
### 3. Scaffold an betternas control-plane service from the start
The repo will include a control-plane service that exposes internal HTTP APIs, owns domain models, and encapsulates policy and orchestration logic. In the first scaffold, this service may be packaged in an ExApp-compatible container, but the code structure SHALL keep Nextcloud-specific integration at the boundary rather than in domain logic.
Rationale:
- Matches the product direction of aiNAS owning the control plane.
- Matches the product direction of betternas owning the control plane.
- Gives one place for RBAC, storage policy, and orchestration logic to live.
- Supports future desktop, iOS, and standalone web surfaces without coupling them to Nextcloud-rendered pages.
@ -66,7 +66,7 @@ The initial scaffold will create clear top-level directories for infrastructure,
Initial structure:
- `docker/`: local orchestration and container assets
- `apps/betternas-controlplane/`: generated Nextcloud shell app
- `exapps/control-plane/`: aiNAS control-plane service, packaged for Nextcloud-compatible dev flows
- `exapps/control-plane/`: betternas control-plane service, packaged for Nextcloud-compatible dev flows
- `packages/contracts/`: shared schemas and API contracts
- `docs/`: architecture and product model notes
- `scripts/`: repeatable developer entry points
@ -82,7 +82,7 @@ Alternatives considered:
### 5. Standardize on a Docker-based local platform first
The first scaffold will target a Docker Compose development environment that starts Nextcloud, its required backing services, and the aiNAS control-plane service. This gives a repeatable local runtime before we decide on production deployment.
The first scaffold will target a Docker Compose development environment that starts Nextcloud, its required backing services, and the betternas control-plane service. This gives a repeatable local runtime before we decide on production deployment.
Rationale:
- Aligns with Nextcloud's easiest local development path.
@ -95,7 +95,7 @@ Alternatives considered:
## Risks / Trade-offs
- [Nextcloud coupling leaks into aiNAS service design] → Keep all Nextcloud-specific API calls and payload translation in adapter modules at the edge of the control-plane service.
- [Nextcloud coupling leaks into betternas service design] → Keep all Nextcloud-specific API calls and payload translation in adapter modules at the edge of the control-plane service.
- [The shell app grows into a second control plane] → Enforce a rule that product decisions and persistent domain logic live in the control-plane service, not the Nextcloud app.
- [ExApp packaging constrains future independence] → Structure the service so container packaging is a deployment concern rather than the application architecture.
- [Initial repo layout may be wrong in details] → Optimize for a small number of strong boundaries now; revisit internal package names later without collapsing ownership boundaries.
@ -116,5 +116,5 @@ Rollback strategy:
- Should the first control-plane service be implemented in Go, Python, or Node/TypeScript?
- What authentication boundary should exist between the Nextcloud shell app and the control-plane service in local development?
- Which parts of future sharing and RBAC behavior should remain delegated to Nextcloud, and which should be modeled natively in aiNAS?
- Which parts of future sharing and RBAC behavior should remain delegated to Nextcloud, and which should be modeled natively in betternas?
- Do we want the first web product surface to live inside Nextcloud pages, outside Nextcloud as a separate frontend, or both?

View file

@ -1,21 +1,21 @@
## Why
aiNAS needs an initial architecture and repository scaffold that lets us build our own storage control plane without inheriting the maintenance cost of a Nextcloud core fork. We want to move quickly on product-specific business logic, but still stand on top of a mature backend for files, sync, sharing primitives, and existing clients.
betternas needs an initial architecture and repository scaffold that lets us build our own storage control plane without inheriting the maintenance cost of a Nextcloud core fork. We want to move quickly on product-specific business logic, but still stand on top of a mature backend for files, sync, sharing primitives, and existing clients.
## What Changes
- Create an initial aiNAS platform scaffold centered on vanilla Nextcloud running in Docker for local development.
- Define a thin Nextcloud app shell that owns aiNAS-specific integration points, branded surfaces, and adapters into the Nextcloud backend.
- Define a control-plane service boundary where aiNAS business logic, policy, and future orchestration will live outside the Nextcloud monolith.
- Create an initial betternas platform scaffold centered on vanilla Nextcloud running in Docker for local development.
- Define a thin Nextcloud app shell that owns betternas-specific integration points, branded surfaces, and adapters into the Nextcloud backend.
- Define a control-plane service boundary where betternas business logic, policy, and future orchestration will live outside the Nextcloud monolith.
- Establish a repository layout for Docker infrastructure, Nextcloud app code, ExApp/service code, and shared API contracts.
- Document the decision to treat Nextcloud as an upstream backend dependency rather than a forked application baseline.
## Capabilities
### New Capabilities
- `workspace-scaffold`: Repository structure and local development platform for running aiNAS with Nextcloud, service containers, and shared packages.
- `nextcloud-shell-app`: Thin aiNAS app inside Nextcloud for navigation, settings, branded entry points, and backend integration hooks.
- `control-plane-service`: External aiNAS service layer that owns business logic and exposes internal APIs used by the Nextcloud shell and future clients.
- `workspace-scaffold`: Repository structure and local development platform for running betternas with Nextcloud, service containers, and shared packages.
- `nextcloud-shell-app`: Thin betternas app inside Nextcloud for navigation, settings, branded entry points, and backend integration hooks.
- `control-plane-service`: External betternas service layer that owns business logic and exposes internal APIs used by the Nextcloud shell and future clients.
### Modified Capabilities
- None.

View file

@ -1,18 +1,18 @@
## ADDED Requirements
### Requirement: Dedicated control-plane service
The system SHALL provide an aiNAS-owned control-plane service that is separate from the Nextcloud shell app and owns product domain logic.
The system SHALL provide an betternas-owned control-plane service that is separate from the Nextcloud shell app and owns product domain logic.
#### Scenario: aiNAS adds a new control-plane rule
#### Scenario: betternas adds a new control-plane rule
- **WHEN** a new business rule for storage policy, RBAC, orchestration, or future client behavior is introduced
- **THEN** the rule MUST be implemented in the control-plane service rather than as primary logic inside the Nextcloud app
### Requirement: Client-agnostic internal API
The control-plane service SHALL expose internal APIs that can be consumed by the Nextcloud shell app and future aiNAS clients without requiring direct coupling to Nextcloud internals.
The control-plane service SHALL expose internal APIs that can be consumed by the Nextcloud shell app and future betternas clients without requiring direct coupling to Nextcloud internals.
#### Scenario: New aiNAS client consumes control-plane behavior
- **WHEN** aiNAS adds a web, desktop, or iOS surface outside Nextcloud
- **THEN** that surface MUST be able to consume control-plane behavior through documented aiNAS service interfaces
#### Scenario: New betternas client consumes control-plane behavior
- **WHEN** betternas adds a web, desktop, or iOS surface outside Nextcloud
- **THEN** that surface MUST be able to consume control-plane behavior through documented betternas service interfaces
### Requirement: Nextcloud backend adapter boundary
The control-plane service SHALL isolate Nextcloud-specific integration at its boundary so that storage and sharing backends remain replaceable over time.

View file

@ -1,22 +1,22 @@
## ADDED Requirements
### Requirement: aiNAS shell app inside Nextcloud
The system SHALL provide a dedicated aiNAS shell app inside Nextcloud that establishes branded entry points for aiNAS-owned product surfaces.
### Requirement: betternas shell app inside Nextcloud
The system SHALL provide a dedicated betternas shell app inside Nextcloud that establishes branded entry points for betternas-owned product surfaces.
#### Scenario: aiNAS surface is visible in Nextcloud
- **WHEN** the aiNAS app is installed in a local development environment
- **THEN** Nextcloud MUST expose an aiNAS-branded application surface that can be used as the integration shell for future product flows
#### Scenario: betternas surface is visible in Nextcloud
- **WHEN** the betternas app is installed in a local development environment
- **THEN** Nextcloud MUST expose an betternas-branded application surface that can be used as the integration shell for future product flows
### Requirement: Thin adapter responsibility
The aiNAS shell app SHALL act as an adapter layer and MUST keep core business logic outside the Nextcloud monolith.
The betternas shell app SHALL act as an adapter layer and MUST keep core business logic outside the Nextcloud monolith.
#### Scenario: Product decision requires domain logic
- **WHEN** the shell app needs information about policy, orchestration, or future product rules
- **THEN** it MUST obtain that information through aiNAS-owned service boundaries instead of embedding the decision logic directly in the app
- **THEN** it MUST obtain that information through betternas-owned service boundaries instead of embedding the decision logic directly in the app
### Requirement: Nextcloud integration hooks
The aiNAS shell app SHALL provide the minimal integration hooks required to connect aiNAS-owned services to Nextcloud runtime surfaces such as navigation, settings, and backend access points.
The betternas shell app SHALL provide the minimal integration hooks required to connect betternas-owned services to Nextcloud runtime surfaces such as navigation, settings, and backend access points.
#### Scenario: aiNAS needs a Nextcloud-native entry point
- **WHEN** aiNAS introduces a new product flow that starts from a Nextcloud-rendered page
- **THEN** the shell app MUST provide a supported hook or page boundary where the flow can enter aiNAS-controlled logic
#### Scenario: betternas needs a Nextcloud-native entry point
- **WHEN** betternas introduces a new product flow that starts from a Nextcloud-rendered page
- **THEN** the shell app MUST provide a supported hook or page boundary where the flow can enter betternas-controlled logic

View file

@ -1,22 +1,22 @@
## ADDED Requirements
### Requirement: Repository boundary scaffold
The repository SHALL provide a top-level scaffold that separates infrastructure, Nextcloud app code, aiNAS-owned service code, shared contracts, documentation, and automation scripts.
The repository SHALL provide a top-level scaffold that separates infrastructure, Nextcloud app code, betternas-owned service code, shared contracts, documentation, and automation scripts.
#### Scenario: Fresh clone exposes expected boundaries
- **WHEN** a developer inspects the repository after applying this change
- **THEN** the repository MUST include dedicated locations for Docker runtime assets, the Nextcloud shell app, the control-plane service, shared contracts, documentation, and scripts
### Requirement: Local development platform
The repository SHALL provide a local development runtime that starts a vanilla Nextcloud instance together with its required backing services and the aiNAS control-plane service.
The repository SHALL provide a local development runtime that starts a vanilla Nextcloud instance together with its required backing services and the betternas control-plane service.
#### Scenario: Developer boots the local stack
- **WHEN** a developer runs the documented local startup flow
- **THEN** the system MUST start Nextcloud and the aiNAS service dependencies without requiring a forked Nextcloud build
- **THEN** the system MUST start Nextcloud and the betternas service dependencies without requiring a forked Nextcloud build
### Requirement: Shared contract package
The repository SHALL include a shared contract location for schemas and service interfaces used between the Nextcloud shell app and aiNAS-owned services.
The repository SHALL include a shared contract location for schemas and service interfaces used between the Nextcloud shell app and betternas-owned services.
#### Scenario: Interface changes are modeled centrally
- **WHEN** aiNAS defines an internal API or payload exchanged between the shell app and the control-plane service
- **WHEN** betternas defines an internal API or payload exchanged between the shell app and the control-plane service
- **THEN** the schema MUST be represented in the shared contracts location rather than duplicated ad hoc across codebases

View file

@ -2,19 +2,19 @@
- [x] 1.1 Create the top-level repository structure for `docker/`, `apps/`, `exapps/`, `packages/`, `docs/`, and `scripts/`
- [x] 1.2 Add a Docker Compose development stack for vanilla Nextcloud and its required backing services
- [x] 1.3 Add the aiNAS control-plane service container to the local development stack
- [x] 1.3 Add the betternas control-plane service container to the local development stack
- [x] 1.4 Add repeatable developer scripts and documentation for booting and stopping the local stack
## 2. Nextcloud shell app scaffold
- [x] 2.1 Generate the aiNAS Nextcloud app scaffold into `apps/betternas-controlplane/`
- [x] 2.2 Configure the shell app with aiNAS branding, navigation entry points, and basic settings surface
- [x] 2.3 Add an adapter layer in the shell app for calling aiNAS-owned service endpoints
- [x] 2.1 Generate the betternas Nextcloud app scaffold into `apps/betternas-controlplane/`
- [x] 2.2 Configure the shell app with betternas branding, navigation entry points, and basic settings surface
- [x] 2.3 Add an adapter layer in the shell app for calling betternas-owned service endpoints
- [x] 2.4 Verify the shell app installs and loads in the local Nextcloud runtime
## 3. Control-plane service scaffold
- [x] 3.1 Scaffold the aiNAS control-plane service in `exapps/control-plane/`
- [x] 3.1 Scaffold the betternas control-plane service in `exapps/control-plane/`
- [x] 3.2 Add a minimal internal HTTP API surface with health and version endpoints
- [x] 3.3 Create a dedicated Nextcloud adapter boundary inside the service for backend integrations
- [x] 3.4 Wire local service configuration so the shell app can discover and call the control-plane service