Qortal-Nextcloud-Integration/docs/nuqloud-blueprint.md

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:

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:

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

Target repo structure

Start with this staged structure in the product fork.

.
├── 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.