102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# 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`
|