This commit is contained in:
Harivansh Rathi 2026-04-01 02:27:08 +00:00
parent 7ae2b7a71c
commit 4ac6275dbf
20 changed files with 83 additions and 83 deletions

View file

@ -1,4 +1,4 @@
# aiNAS # betterNAS
<img width="723" height="354" alt="image" src="https://github.com/user-attachments/assets/4e64fa91-315b-4a31-b191-d54ed1862ff7" /> <img width="723" height="354" alt="image" src="https://github.com/user-attachments/assets/4e64fa91-315b-4a31-b191-d54ed1862ff7" />
@ -8,4 +8,4 @@ The intended boundary is documented in `docs/architecture.md`. The short version
- Nextcloud remains an upstream storage and client-compatibility backend. - Nextcloud remains an upstream storage and client-compatibility backend.
- The custom Nextcloud app is a shell and adapter layer. - The custom Nextcloud app is a shell and adapter layer.
- aiNAS business logic lives in the control-plane service. - betterNAS business logic lives in the control-plane service.

View file

@ -2,12 +2,12 @@
<info xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <info xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://apps.nextcloud.com/schema/apps/info.xsd"> xsi:noNamespaceSchemaLocation="https://apps.nextcloud.com/schema/apps/info.xsd">
<id>ainascontrolplane</id> <id>ainascontrolplane</id>
<name>aiNAS Control Plane</name> <name>betterNAS Control Plane</name>
<summary>Thin aiNAS shell app for Nextcloud integration</summary> <summary>Thin betterNAS shell app for Nextcloud integration</summary>
<description>Provides aiNAS-branded entry points inside Nextcloud while delegating business logic to the aiNAS control plane.</description> <description>Provides betterNAS-branded entry points inside Nextcloud while delegating business logic to the betterNAS control plane.</description>
<version>0.1.0</version> <version>0.1.0</version>
<licence>AGPL-3.0-or-later</licence> <licence>AGPL-3.0-or-later</licence>
<author homepage="https://ainas.local">aiNAS</author> <author homepage="https://ainas.local">betterNAS</author>
<namespace>AinasControlplane</namespace> <namespace>AinasControlplane</namespace>
<category>integration</category> <category>integration</category>
<dependencies> <dependencies>
@ -16,7 +16,7 @@
<navigations> <navigations>
<navigation> <navigation>
<id>ainascontrolplane</id> <id>ainascontrolplane</id>
<name>aiNAS</name> <name>betterNAS</name>
<route>ainascontrolplane.page.index</route> <route>ainascontrolplane.page.index</route>
<icon>app.svg</icon> <icon>app.svg</icon>
<type>link</type> <type>link</type>

View file

@ -1,6 +1,6 @@
{ {
"name": "ainas/ainascontrolplane", "name": "ainas/ainascontrolplane",
"description": "aiNAS Nextcloud shell app", "description": "betterNAS Nextcloud shell app",
"license": "AGPL-3.0-or-later", "license": "AGPL-3.0-or-later",
"autoload": { "autoload": {
"psr-4": { "psr-4": {

View file

@ -33,7 +33,7 @@ class PageController extends Controller {
Application::APP_ID, Application::APP_ID,
'index', 'index',
[ [
'appName' => 'aiNAS Control Plane', 'appName' => 'betterNAS Control Plane',
'controlPlaneUrl' => $this->controlPlaneConfig->getBaseUrl(), 'controlPlaneUrl' => $this->controlPlaneConfig->getBaseUrl(),
'snapshot' => $this->controlPlaneClient->fetchSnapshot(), 'snapshot' => $this->controlPlaneClient->fetchSnapshot(),
], ],

View file

@ -33,7 +33,7 @@ class ControlPlaneClient {
'version' => $versionResponse['body'], 'version' => $versionResponse['body'],
]; ];
} catch (\Throwable $exception) { } catch (\Throwable $exception) {
$this->logger->warning('Failed to reach aiNAS control plane', [ $this->logger->warning('Failed to reach betterNAS control plane', [
'exception' => $exception, 'exception' => $exception,
'url' => $baseUrl, 'url' => $baseUrl,
]); ]);

View file

@ -21,7 +21,7 @@ class AdminSection implements IIconSection {
} }
public function getName(): string { public function getName(): string {
return $this->l->t('aiNAS'); return $this->l->t('betterNAS');
} }
public function getPriority(): int { public function getPriority(): int {

View file

@ -15,7 +15,7 @@ $version = $snapshot['version']['version'] ?? 'unreachable';
<div class="ainas-shell ainas-shell--admin"> <div class="ainas-shell ainas-shell--admin">
<div class="ainas-shell__hero"> <div class="ainas-shell__hero">
<p class="ainas-shell__eyebrow">Admin settings</p> <p class="ainas-shell__eyebrow">Admin settings</p>
<h1 class="ainas-shell__title">aiNAS control-plane wiring</h1> <h1 class="ainas-shell__title">betterNAS control-plane wiring</h1>
<p class="ainas-shell__copy"> <p class="ainas-shell__copy">
The local scaffold wires this app to the control plane through the <code>AINAS_CONTROL_PLANE_URL</code> environment variable in the Nextcloud container. The local scaffold wires this app to the control plane through the <code>AINAS_CONTROL_PLANE_URL</code> environment variable in the Nextcloud container.
</p> </p>

View file

@ -15,10 +15,10 @@ $error = $snapshot['error'] ?? null;
<div class="ainas-shell"> <div class="ainas-shell">
<div class="ainas-shell__hero"> <div class="ainas-shell__hero">
<p class="ainas-shell__eyebrow">aiNAS inside Nextcloud</p> <p class="ainas-shell__eyebrow">betterNAS inside Nextcloud</p>
<h1 class="ainas-shell__title"><?php p($_['appName']); ?></h1> <h1 class="ainas-shell__title"><?php p($_['appName']); ?></h1>
<p class="ainas-shell__copy"> <p class="ainas-shell__copy">
This shell app stays intentionally thin. It exposes aiNAS entry points inside Nextcloud and delegates business logic to the external control-plane service. This shell app stays intentionally thin. It exposes betterNAS entry points inside Nextcloud and delegates business logic to the external control-plane service.
</p> </p>
</div> </div>
@ -42,7 +42,7 @@ $error = $snapshot['error'] ?? null;
<h2>Boundary</h2> <h2>Boundary</h2>
<ul> <ul>
<li>Nextcloud provides file and client primitives.</li> <li>Nextcloud provides file and client primitives.</li>
<li>aiNAS owns control-plane policy and orchestration.</li> <li>betterNAS owns control-plane policy and orchestration.</li>
<li>The shell app only adapts between the two.</li> <li>The shell app only adapts between the two.</li>
</ul> </ul>
</section> </section>

View file

@ -1,12 +1,12 @@
# aiNAS decision scaffold # betterNAS decision scaffold
STEAL NOW OWN NOW STEAL NOW OWN NOW
------------------- ------------------- ------------------- -------------------
Nextcloud server aiNAS control plane Nextcloud server betterNAS control plane
Nextcloud desktop aiNAS product API Nextcloud desktop betterNAS product API
Nextcloud iOS aiNAS policy model Nextcloud iOS betterNAS policy model
Nextcloud external storage aiNAS device model Nextcloud external storage betterNAS device model
Nextcloud sharing UI aiNAS mount model Nextcloud sharing UI betterNAS mount model
LATER LATER
----------------------- -----------------------
@ -20,10 +20,10 @@
+--> Nextcloud web shell/app --------\ +--> Nextcloud web shell/app --------\
| - login/session | | - login/session |
| - file/share UI | | - file/share UI |
| - thin aiNAS entry page | | - thin betterNAS entry page |
| - OCS route | | - OCS route |
| v | v
+--> Nextcloud desktop/iOS ----> aiNAS control plane ----> storage backends +--> Nextcloud desktop/iOS ----> betterNAS control plane ----> storage backends
- Finder presence - devices - NAS / SMB / S3 - Finder presence - devices - NAS / SMB / S3
- sync / virtual files - policies - NFS / WebDAV - sync / virtual files - policies - NFS / WebDAV
- mobile app - shares/mounts - local/ZFS/etc - mobile app - shares/mounts - local/ZFS/etc

View file

@ -1,18 +1,18 @@
# aiNAS Architecture Boundary # betterNAS Architecture Boundary
## Core Decision ## Core Decision
aiNAS treats Nextcloud as an upstream backend, not as the place where aiNAS product logic should accumulate. betterNAS treats Nextcloud as an upstream backend, not as the place where betterNAS product logic should accumulate.
That leads to three explicit boundaries: That leads to three explicit boundaries:
1. `apps/ainas-controlplane/` is a thin shell inside Nextcloud. 1. `apps/ainas-controlplane/` is a thin shell inside Nextcloud.
2. `exapps/control-plane/` owns aiNAS business logic and internal APIs. 2. `exapps/control-plane/` owns betterNAS business logic and internal APIs.
3. `packages/contracts/` defines the interface between the shell app and the control plane. 3. `packages/contracts/` defines the interface between the shell app and the control plane.
## Why This Boundary Exists ## Why This Boundary Exists
Forking `nextcloud/server` would force aiNAS to own upstream patching and compatibility work too early. Pushing aiNAS logic into a traditional Nextcloud app would make the product harder to evolve outside the PHP monolith. The scaffold in this repository is designed to avoid both traps. Forking `nextcloud/server` would force betterNAS to own upstream patching and compatibility work too early. Pushing betterNAS logic into a traditional Nextcloud app would make the product harder to evolve outside the PHP monolith. The scaffold in this repository is designed to avoid both traps.
## Responsibilities ## Responsibilities
@ -22,12 +22,12 @@ The shell app is responsible for:
- navigation entries - navigation entries
- branded entry pages inside Nextcloud - branded entry pages inside Nextcloud
- admin-facing integration surfaces - admin-facing integration surfaces
- adapter calls into the aiNAS control plane - adapter calls into the betterNAS control plane
The shell app is not responsible for: The shell app is not responsible for:
- storage policy rules - storage policy rules
- orchestration logic - orchestration logic
- aiNAS-native RBAC decisions - betterNAS-native RBAC decisions
- product workflows that may later be reused by desktop, iOS, or standalone web clients - product workflows that may later be reused by desktop, iOS, or standalone web clients
### Control-plane service ### Control-plane service
@ -35,7 +35,7 @@ The shell app is not responsible for:
The control plane is responsible for: The control plane is responsible for:
- domain logic - domain logic
- policy decisions - policy decisions
- internal APIs consumed by aiNAS surfaces - internal APIs consumed by betterNAS surfaces
- Nextcloud integration adapters kept at the service boundary - Nextcloud integration adapters kept at the service boundary
### Shared contracts ### Shared contracts
@ -48,7 +48,7 @@ The local development stack uses Docker Compose so developers can bring up:
- Nextcloud - Nextcloud
- PostgreSQL - PostgreSQL
- Redis - Redis
- the aiNAS control-plane service - the betterNAS control-plane service
The Nextcloud shell app is mounted as a custom app and enabled through `./scripts/dev-up`. The Nextcloud shell app is mounted as a custom app and enabled through `./scripts/dev-up`.

View file

@ -5,6 +5,6 @@ const config = loadConfig();
const app = createApp(config); const app = createApp(config);
app.listen(config.port, "0.0.0.0", () => { app.listen(config.port, "0.0.0.0", () => {
console.log(`aiNAS control plane listening on port ${config.port}`); console.log(`betterNAS control plane listening on port ${config.port}`);
}); });

View file

@ -11,7 +11,7 @@
# basic non-verified structure off the top of my head # basic non-verified structure off the top of my head
aiNAS/ betterNAS/
docker/ docker/
compose.dev.yml compose.dev.yml
nextcloud/ nextcloud/

View file

@ -1,16 +1,16 @@
## Context ## 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 / Non-Goals
**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 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. - 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 aiNAS services rather than Nextcloud internals. - 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. - Make the initial architecture easy to extend without forcing a Nextcloud core fork.
**Non-Goals:** **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 ### 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: Rationale:
- Keeps upstream upgrades and security patches tractable. - 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 ### 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: Rationale:
- Keeps PHP app code small and replaceable. - Keeps PHP app code small and replaceable.
@ -46,12 +46,12 @@ Rationale:
Alternatives considered: Alternatives considered:
- Put most logic directly in the app: rejected because it couples product evolution to the monolith. - 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. 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: 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. - 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. - 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: Initial structure:
- `docker/`: local orchestration and container assets - `docker/`: local orchestration and container assets
- `apps/ainas-controlplane/`: generated Nextcloud shell app - `apps/ainas-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 - `packages/contracts/`: shared schemas and API contracts
- `docs/`: architecture and product model notes - `docs/`: architecture and product model notes
- `scripts/`: repeatable developer entry points - `scripts/`: repeatable developer entry points
@ -82,7 +82,7 @@ Alternatives considered:
### 5. Standardize on a Docker-based local platform first ### 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: Rationale:
- Aligns with Nextcloud's easiest local development path. - Aligns with Nextcloud's easiest local development path.
@ -95,7 +95,7 @@ Alternatives considered:
## Risks / Trade-offs ## 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. - [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. - [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. - [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? - 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? - 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? - 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 ## 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 ## What Changes
- Create an initial aiNAS platform scaffold centered on vanilla Nextcloud running in Docker for local development. - Create an initial betterNAS 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 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 aiNAS business logic, policy, and future orchestration will live outside the Nextcloud monolith. - 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. - 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. - Document the decision to treat Nextcloud as an upstream backend dependency rather than a forked application baseline.
## Capabilities ## Capabilities
### New Capabilities ### New Capabilities
- `workspace-scaffold`: Repository structure and local development platform for running aiNAS with Nextcloud, service containers, and shared packages. - `workspace-scaffold`: Repository structure and local development platform for running betterNAS 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. - `nextcloud-shell-app`: Thin betterNAS 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. - `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 ### Modified Capabilities
- None. - None.

View file

@ -1,18 +1,18 @@
## ADDED Requirements ## ADDED Requirements
### Requirement: Dedicated control-plane service ### 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 - **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 - **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 ### 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 #### Scenario: New betterNAS client consumes control-plane behavior
- **WHEN** aiNAS adds a web, desktop, or iOS surface outside Nextcloud - **WHEN** betterNAS 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 - **THEN** that surface MUST be able to consume control-plane behavior through documented betterNAS service interfaces
### Requirement: Nextcloud backend adapter boundary ### 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. 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 ## ADDED Requirements
### Requirement: aiNAS shell app inside Nextcloud ### Requirement: betterNAS 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. 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 #### Scenario: betterNAS surface is visible in Nextcloud
- **WHEN** the aiNAS app is installed in a local development environment - **WHEN** the betterNAS 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 - **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 ### 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 #### Scenario: Product decision requires domain logic
- **WHEN** the shell app needs information about policy, orchestration, or future product rules - **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 ### 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 #### Scenario: betterNAS needs a Nextcloud-native entry point
- **WHEN** aiNAS introduces a new product flow that starts from a Nextcloud-rendered page - **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 aiNAS-controlled logic - **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 ## ADDED Requirements
### Requirement: Repository boundary scaffold ### 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 #### Scenario: Fresh clone exposes expected boundaries
- **WHEN** a developer inspects the repository after applying this change - **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 - **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 ### 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 #### Scenario: Developer boots the local stack
- **WHEN** a developer runs the documented local startup flow - **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 ### 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 #### 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 - **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.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.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 - [x] 1.4 Add repeatable developer scripts and documentation for booting and stopping the local stack
## 2. Nextcloud shell app scaffold ## 2. Nextcloud shell app scaffold
- [x] 2.1 Generate the aiNAS Nextcloud app scaffold into `apps/ainas-controlplane/` - [x] 2.1 Generate the betterNAS Nextcloud app scaffold into `apps/ainas-controlplane/`
- [x] 2.2 Configure the shell app with aiNAS branding, navigation entry points, and basic settings surface - [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 aiNAS-owned service endpoints - [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 - [x] 2.4 Verify the shell app installs and loads in the local Nextcloud runtime
## 3. Control-plane service scaffold ## 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.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.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 - [x] 3.4 Wire local service configuration so the shell app can discover and call the control-plane service

View file

@ -1,7 +1,7 @@
aiNAS repo betterNAS repo
│ apps/ainas-controlplane │ apps/ainas-controlplane
│ PHP Nextcloud app │ PHP Nextcloud app
│ - nav entry: "aiNAS" │ - nav entry: "betterNAS"
│ - page route: /index.php/apps/ainascontrolplane/ │ - page route: /index.php/apps/ainascontrolplane/
│ - OCS route: /ocs/v2.php/apps/ainascontrolplane/api/status │ - OCS route: /ocs/v2.php/apps/ainascontrolplane/api/status
│ - job today: call control-plane and render a thin shell │ - job today: call control-plane and render a thin shell

View file

@ -63,4 +63,4 @@ fi
nextcloud_occ app:enable --force ainascontrolplane >/dev/null nextcloud_occ app:enable --force ainascontrolplane >/dev/null
echo "Nextcloud: http://localhost:8080" echo "Nextcloud: http://localhost:8080"
echo "aiNAS control plane: http://localhost:3001" echo "betterNAS control plane: http://localhost:3001"