# 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`