aiNAS Architecture Boundary

Core Decision

aiNAS treats Nextcloud as an upstream backend, not as the place where aiNAS product logic should accumulate.

That leads to three explicit boundaries:

apps/betternas-controlplane/ is a thin shell inside Nextcloud.
exapps/control-plane/ owns aiNAS business logic and internal APIs.
packages/contracts/ defines the interface between the shell app and the control plane.

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.

Responsibilities

Nextcloud shell app

The shell app is responsible for:

navigation entries
branded entry pages inside Nextcloud
admin-facing integration surfaces
adapter calls into the aiNAS control plane

The shell app is not responsible for:

storage policy rules
orchestration logic
aiNAS-native RBAC decisions
product workflows that may later be reused by desktop, iOS, or standalone web clients

Control-plane service

The control plane is responsible for:

domain logic
policy decisions
internal APIs consumed by aiNAS surfaces
Nextcloud integration adapters kept at the service boundary

Shared contracts

Contracts live in packages/contracts/ so request and response shapes do not get duplicated between PHP and TypeScript codebases.

Local Runtime

The local development stack uses Docker Compose so developers can bring up:

Nextcloud
PostgreSQL
Redis
the aiNAS control-plane service

The Nextcloud shell app is mounted as a custom app and enabled through ./scripts/dev-up.

1.7 KiB Raw Blame History