# NuQloud Blueprint

This document defines the target repo layout, branch strategy, and feature-flag matrix for the productized fork:

- Core upstream: `crowetic/Qortal-Nextcloud-Integration`
- Product fork: `NuQloud/NuQloud-Nextcloud`

Companion docs:

1. `docs/product/prd-v1.md`
2. `docs/product/v1-feature-scope.md`
3. `docs/product/v1-functions.md`
4. `docs/engineering/implementation-matrix.md`
5. `docs/engineering/milestone-issue-list.md`
6. `docs/product/pricing-packages-v1.md`
7. `docs/engineering/billing-architecture-v1.md`
8. `docs/product/paymenter-readonly-setup.md`

## Git strategy

Recommended workflow:

1. Keep `origin` pointed to core upstream.
2. Keep `nuqloud` pointed to product fork.
3. Do product work on product branches, not `main`.

Example commands:

```bash
git remote add nuqloud https://gitea.qortal.link/NuQloud/NuQloud-Nextcloud.git
git switch -c nuqloud-bootstrap
git push -u nuqloud nuqloud-bootstrap
```

Sync core updates into product fork:

```bash
git fetch origin
git switch nuqloud-bootstrap
git merge origin/main
```

## Target repo structure

Start with this staged structure in the product fork.

```text
.
├── nextcloud/
│   └── custom_apps/
│       └── qortal_integration/              # Keep internal app ID for compatibility
├── services/
│   ├── qortal-oidc-broker/                  # Keep as auth/provision core
│   └── nuqloud-control-plane/               # Future: tiering, credit ledger, ops APIs
├── deploy/
│   ├── templates/
│   │   ├── qortal/
│   │   ├── nginx/
│   │   └── apache/
│   └── installers/
│       ├── docker/
│       └── vm/
├── scripts/
│   ├── install-production-docker.sh
│   ├── nextcloud-vm-install.sh
│   └── setup-wizards/
├── docs/
│   ├── product/
│   │   ├── modes.md
│   │   ├── pricing-tiers.md
│   │   ├── security-model.md
│   │   └── backup-replication.md
│   └── engineering/
│       ├── feature-flags.md
│       └── migration-plan.md
└── Makefile
```

## Product modes

Two modes should be first-class and switchable at runtime:

1. `powered` mode:
   - Qortal hidden behind NuQloud language.
   - QORT shown as credits (or hidden if policy requires).
   - End-user UI minimizes protocol details.
2. `full_qortal` mode:
   - Current Qortal-native UX/terms.
   - Full Q-Apps and Qortal terminology.
   - Best for existing Qortal communities.

## Feature flag matrix (v1)

Use server-side flags persisted in Nextcloud app config and mirrored to broker/external-auth where relevant.

| Flag | Type | Default `powered` | Default `full_qortal` | Scope | Notes |
|---|---|---:|---:|---|---|
| `SC_MODE` (`powered`,`full_qortal`) | enum | `powered` | `full_qortal` | global | Master product mode |
| `SC_SHOW_QORTAL_BRANDING` | bool | false | true | UI | Logos/text/terminology |
| `SC_ENABLE_QAPPS` | bool | true | true | UI/API | App launcher + browser |
| `SC_ENABLE_QAPPS_DEBUG` | bool | false | true | UI | Debug panel + advanced internals |
| `SC_ENABLE_FULL_BROWSER_MODE` | bool | false | true | UI | Arbitrary qortal:// browsing |
| `SC_ENABLE_DIRECT_QORTAL_LOGIN` | bool | false | true | auth | Show native Qortal login path |
| `SC_ENABLE_NEW_QORTAL_ACCOUNT_ONBOARDING` | bool | true | true | auth | Create+link flow |
| `SC_REQUIRE_EMAIL_FOR_NEW_ACCOUNTS` | bool | true | false | auth | Enforce email field for new users |
| `SC_REQUIRE_INVITE_OR_ALLOWLIST` | bool | true | configurable | auth | Guard for auto-provision |
| `SC_ENABLE_SESSION_AUTO_REFRESH` | bool | true | true | broker | Keep ext-auth session aligned to NC session |
| `SC_SHOW_WALLET_PASSWORD_PROMPTS` | bool | conditional | conditional | auth UX | Only when wallet unlock required |
| `SC_ENABLE_APPROVAL_AUTOMATION` | bool | true | true | auth UX | Type/app policy saves |
| `SC_ENABLE_PER_APP_APPROVAL` | bool | true | true | auth UX | Scope by app URI |
| `SC_ENABLE_PER_TYPE_APPROVAL` | bool | true | true | auth UX | Scope by request type |
| `SC_ENABLE_NUQLOUD_BACKUPS` | bool | true | true | backup | Backup publish/restore UX |
| `SC_ENABLE_REPLICATION_PACKAGES` | bool | false | false | backup | Paid tier feature gate |
| `SC_ENABLE_ZERO_ACCESS_REPLICATION` | bool | false | false | backup | Encrypted/chunked replication only |
| `SC_ENABLE_CREDIT_LEDGER` | bool | true | optional | billing | Internal usage accounting |
| `SC_HIDE_QORT_AS_CREDITS` | bool | true | false | billing/UI | Display abstraction layer |
| `SC_ENABLE_ADMIN_QORT_REQUEST_QUEUE` | bool | true | true | admin | Initial funding workflow |
| `SC_ENABLE_VENDORLESS_OIDC_COPY` | bool | true | true | UI/docs | NuQloud identity messaging |

## Configuration model

Rule of thumb:

1. Security and transport settings: env vars (`.env*`) + startup scripts.
2. Product behavior flags: Nextcloud app config (admin panel).
3. Runtime mirrors: best-effort sync from app config to broker/external-auth for applicable keys.

## Milestones for the fork

1. `M1 Rebrand foundation`
   - Keep app id as `qortal_integration` and rebrand display/UI labels
   - Add mode switch + compatibility layer
2. `M2 Powered mode UX`
   - Credit language, simplified onboarding, low-friction dashboard
3. `M3 Full mode parity`
   - Preserve all current Qortal-native capabilities
4. `M4 NuQloud backups + replication packages`
   - Chunked encrypted backup publishing + verification + restore UX
5. `M5 Tiering/billing integration`
   - Feature gating and metering hooks for paid offerings

## Non-negotiables

1. No plaintext password storage.
2. Broker endpoints never exposed without internal auth token.
3. Deterministic migration path `powered -> full_qortal` without account breakage.
4. Data portability first: export/import across providers and devices.