Qortal-Nextcloud-Integration/docs/engineering/implementation-matrix.md

NuQloud Implementation Matrix

This maps product requirements to concrete implementation surfaces.

1. System surfaces

1. nextcloud/custom_apps/*:
   • admin/user UI - (maybe only admins can control backups? - Users just aware of features? - determine best path.)
   • settings persistence
   • mode-specific UX
2. services/qortal-oidc-broker/*:
   • OIDC broker
   • provisioning bridge
   • internal auth/cors enforcement
3. external-auth integration:
   • session lifecycle
   • wallet/approval flow
   • request transport semantics
4. scripts/* + deploy/*:
   • install/recreate automation
   • runtime env defaults
5. docs/*:
   • admin/operator documentation
   • claims and terminology consistency

2. Feature matrix

Feature	Nextcloud App	Broker	External Auth	Scripts/Deploy	Docs
SC_MODE switch	Add admin mode toggle + UI conditionals	Expose mode-aware metadata endpoint (optional)	N/A	Set default in install scripts	Mode guide
NuQloud naming in powered mode	Replace labels/copy strings via mode map	N/A	N/A	N/A	Language policy
Full Qortal mode parity	Keep existing components behind flags	Keep existing routes stable	Existing	N/A	Full mode guide
OIDC identity provider	OIDC app setup + mappings	Maintain issuer/jwks/token/userinfo	Session-backed qortal requests	Env scaffolding	OIDC setup doc
Internal broker token auth	Send header from app	Enforce token middleware	N/A	Generate + export token	Security docs
Session auto-refresh	Handle retries in app UI	Recover session on 401	Provide session endpoint	Ensure env values set	Troubleshooting
Approval policy UX	Mode-aware modal/settings	N/A	Permission endpoints	N/A	User/admin docs
NuQloud backups	Admin controls + status UI	Backup orchestration endpoint(s)	Request handlers	Schedule defaults	Backup docs
Replication guarantees	Status dashboard + alerts	Status aggregation API	(if involved)	Tier/env template	Package docs
Credits abstraction	Show credits not QORT in powered	Optional metering API	N/A	Tier defaults	Pricing docs
QORT request queue	User request + admin actions	Optional notify API	Transaction call path	N/A	Ops guide
Debug mode isolation	Admin-only toggle + warning	Optional debug endpoint gating	N/A	Disable in prod templates	Debug policy

3. Flag-to-storage mapping

Flag family	Source of truth	Mirror target
UI/mode flags	Nextcloud app config	Optional runtime cache
Security runtime (token/cors)	.env*	broker process env
External-auth node settings	.env* + admin sync	external-auth runtime
Package/tier limits	Nextcloud app config (or control plane DB)	broker/app runtime

4. Data model additions (proposed)

1. sc_mode:
   • enum: powered, full_qortal
2. sc_flags:
   • JSON object of booleans/limits
3. sc_credit_ledger:
   • id, tenant, event_type, delta, balance_after, metadata, created_at
4. sc_replication_status:
   • tenant, target_replicas, healthy_replicas, last_verified_at, state
5. sc_backup_proofs:
   • backup_id, proof_hash, published_at, integrity_state

5. Cross-cutting constraints

1. No breaking changes to existing OIDC mapping behavior.
2. Existing full-qortal flows must remain available when SC_MODE=full_qortal.
3. Powered mode must hide direct wallet semantics in UI strings.
4. Runtime scripts must fail fast when required security env is missing.

6. Test matrix (minimum)

1. Mode switch regression:
   • powered -> full_qortal -> powered
2. OIDC auth:
   • new user invite flow
   • existing mapped user flow
3. Backup:
   • create backup proof
   • verify restore preview
4. Replication:
   • healthy state
   • degraded state
5. Security:
   • direct broker API call without token fails
   • with token succeeds

7. Migration and compatibility

1. Existing installs default to full_qortal on first upgrade.
2. New installs default to powered.
3. Add migration command to seed flags with safe defaults.
4. Keep reversible mapping for terminology and settings.

8. Billing architecture companion

Detailed billing/credits implementation spec:

1. docs/product/pricing-packages-v1.md
2. docs/engineering/billing-architecture-v1.md