betterNAS/docs/architecture.md

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:

1. apps/ainas-controlplane/ is a thin shell inside Nextcloud.
2. exapps/control-plane/ owns aiNAS business logic and internal APIs.
3. 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.