add local dev setup

Co-authored-by: Codex <noreply@openai.com>

README.md

@@ -0,0 +1,51 @@
+# aiNAS
+
+aiNAS is a storage control-plane project that uses vanilla Nextcloud as an upstream backend instead of forking the core server. This repository starts with the foundational pieces we need to build our own product surfaces while keeping file primitives, sync compatibility, and existing client integrations delegated to Nextcloud.
+
+## Repository Layout
+
+- `docker/`: local development runtime for Nextcloud and aiNAS services
+- `apps/ainas-controlplane/`: thin Nextcloud shell app
+- `exapps/control-plane/`: aiNAS-owned control-plane service
+- `packages/contracts/`: shared API contracts used by aiNAS services and adapters
+- `docs/`: architecture and development notes
+- `scripts/`: repeatable developer workflows
+
+## Local Development
+
+Requirements:
+- Docker with Compose support
+- Node.js 22+
+- npm 10+
+
+Bootstrap the JavaScript workspace:
+
+```bash
+npm install
+```
+
+Start the local stack:
+
+```bash
+./scripts/dev-up
+```
+
+Stop the local stack:
+
+```bash
+./scripts/dev-down
+```
+
+Once the stack is up:
+- Nextcloud: `http://localhost:8080`
+- aiNAS control plane: `http://localhost:3001`
+
+The `dev-up` script waits for Nextcloud installation to finish and then enables the `ainascontrolplane` custom app inside the container.
+
+## Architecture
+
+The intended boundary is documented in `docs/architecture.md`. The short version is:
+
+- Nextcloud remains an upstream storage and client-compatibility backend.
+- The custom Nextcloud app is a shell and adapter layer.
+- aiNAS business logic lives in the control-plane service.

docker/compose.dev.yml

@@ -0,0 +1,75 @@
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: nextcloud
+      POSTGRES_USER: nextcloud
+      POSTGRES_PASSWORD: nextcloud
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U nextcloud -d nextcloud"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+    volumes:
+      - redis-data:/data
+
+  control-plane:
+    build:
+      context: ..
+      dockerfile: exapps/control-plane/Dockerfile
+    environment:
+      PORT: 3000
+      AINAS_VERSION: local-dev
+      NEXTCLOUD_BASE_URL: http://nextcloud
+    ports:
+      - "3001:3000"
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "node -e \"fetch('http://127.0.0.1:3000/health').then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))\""
+        ]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+  nextcloud:
+    image: nextcloud:31-apache
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      control-plane:
+        condition: service_healthy
+    environment:
+      POSTGRES_HOST: db
+      POSTGRES_DB: nextcloud
+      POSTGRES_USER: nextcloud
+      POSTGRES_PASSWORD: nextcloud
+      REDIS_HOST: redis
+      NEXTCLOUD_ADMIN_USER: admin
+      NEXTCLOUD_ADMIN_PASSWORD: admin
+      AINAS_CONTROL_PLANE_URL: http://control-plane:3000
+    ports:
+      - "8080:80"
+    volumes:
+      - nextcloud-data:/var/www/html
+      - ../apps/ainas-controlplane:/var/www/html/custom_apps/ainascontrolplane
+
+volumes:
+  nextcloud-data:
+  postgres-data:
+  redis-data:
+

docs/architecture.md

@@ -0,0 +1,54 @@
+# 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`.
+

scripts/dev-down

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+compose_file="$repo_root/docker/compose.dev.yml"
+
+docker compose -f "$compose_file" down --remove-orphans
+

scripts/dev-up

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+compose_file="$repo_root/docker/compose.dev.yml"
+
+docker compose -f "$compose_file" up -d --build
+
+echo "Waiting for Nextcloud to finish installing..."
+ready=0
+for _ in {1..60}; do
+  if docker compose -f "$compose_file" exec -T --user www-data nextcloud php occ status >/dev/null 2>&1; then
+    ready=1
+    break
+  fi
+  sleep 2
+done
+
+if [[ "$ready" -ne 1 ]]; then
+  echo "Nextcloud did not become ready in time." >&2
+  exit 1
+fi
+
+docker compose -f "$compose_file" exec -T --user www-data nextcloud php occ app:enable --force ainascontrolplane >/dev/null
+
+echo "Nextcloud: http://localhost:8080"
+echo "aiNAS control plane: http://localhost:3001"