Qortal-Nextcloud-Integration/docs/future-plans/NuQloud-world/nuqloud-world-next-gen-interface-implementation-plan.md

NuQloud World Next-Generation Interface Implementation Plan

Purpose

Build NuQloud World as an optional, plugin-delivered theme/interface layer for NuQloud for Nextcloud. The goal is a living cloud command environment that adds spatial navigation, motion, service status, and QDN publishing workflows on top of NuQloud-native surfaces.

NuQloud World must be built as a theme-grade Nextcloud app/plugin wherever possible. It must not require a maintained Nextcloud fork, and it must not become a second dashboard product.

Source Inputs

This plan is based on:

• The NuQloud World Interface build and rollout plan.
• Concept screenshots in docs/future-plans/NuQloud-world/Concept-Screenshots/Interface-ReBrand-Concept-1/.
• Website and architecture concepts in docs/future-plans/NuQloud-world/Concept-Screenshots/NuQloud-Website-Concept/.
• Current app and plugin boundary notes in docs/plugin-roadmap.md.
• Product mode guidance in docs/nuqloud-blueprint.md.

Dependency Note

Phaser 4 is now a viable planning target, but the implementation should pin an exact version during Phase 0.

Official references checked while preparing this plan:

• Phaser 4 overview: https://phaser.io/phaser4
• Stable Phaser download page: https://phaser.io/download/stable
• Phaser GitHub releases: https://github.com/phaserjs/phaser/releases

As of July 6, 2026, Phaser's stable download page lists Phaser v4.2.0 released on June 19, 2026. Do not depend on unpinned latest packages.

Product Positioning

NuQloud World is not a game. It is a spatial cloud interface for:

• Files and protected storage.
• Private communication.
• Deck tasks and projects.
• QDN publishing.
• Instance health and operational status.
• Account and identity state.

The existing NuQloud surfaces remain the productivity layer. World Mode is the optional "wow layer" and should feel like a deep theme over the same product, not a separate dashboard users must learn from scratch.

Theme-Grade Plugin Architecture

Recommended App Shape

Create a new Nextcloud app that behaves as a NuQloud theme/interface shell:

nuqloud_world/
+-- appinfo/
|   +-- info.xml
|   +-- routes.php
+-- lib/
|   +-- AppInfo/Application.php
|   +-- Controller/PageController.php
|   +-- Controller/Api/WorldStateController.php
|   +-- Controller/Api/PublishController.php
|   +-- Service/WorldStateService.php
|   +-- Service/FeatureFlagService.php
|   +-- Service/Integration/
|   |   +-- CoreIntegration.php
|   |   +-- FilesBridgeIntegration.php
|   |   +-- TalkBridgeIntegration.php
|   |   +-- QdnIntegration.php
|   +-- Db/
|       +-- WorldPreferenceMapper.php
|       +-- WorldPreference.php
+-- src/
|   +-- main.tsx
|   +-- app/
|   +-- phaser/
|   +-- ui/
|   +-- api/
|   +-- state/
|   +-- events/
|   +-- theme/
|   +-- i18n/
|   +-- types/
+-- templates/
|   +-- world.php
+-- img/
+-- css/
+-- package.json

Integration Boundaries

The theme/interface plugin should depend on existing app capabilities instead of duplicating them:

• qortal_integration: account state, identity state, feature flags, QDN API gateway configuration, product language mode.
• qortal_files_bridge: file publish state, protected folder state, QDN file publish actions.
• qortal_talk_bridge: conversation summary, unread counts, relay state.
• NuQloud Deck surface: task/project summaries.
• custom_pwa: future install/deep-link affordances only.

CHD admin tooling must remain internal-only and must not be exposed through NuQloud World.

Q-Deck is the QDN-native app and is out of scope for this NuQloud-native interface plan. Cross-collaboration between NuQloud Deck and Q-Deck should be handled by a separate future plugin.

Runtime Model

Authenticated user
-> /apps/nuqloud_world/world
-> Nextcloud controller renders shell
-> compiled React + Phaser bundle loads
-> client requests /apps/nuqloud_world/api/state
-> server aggregates allowed state from installed apps
-> Phaser renders world state
-> HTML panels perform real actions

Phaser owns visual interaction only:

• Background scene.
• Spatial service map.
• Hover and focus effects.
• Activity pulses.
• Service status visualization.
• QDN portal animation.
• Optional drag/drop affordances.

HTML/React owns productive work:

• File lists.
• Forms.
• Publish confirmation.
• Message previews.
• Task details.
• Admin status.
• Settings.
• Accessibility fallback controls.

Rule: Phaser emits intent; the app executes business logic.

Routes

Authenticated routes:

GET  /apps/nuqloud_world/world
GET  /apps/nuqloud_world/settings
GET  /apps/nuqloud_world/api/state
GET  /apps/nuqloud_world/api/services
GET  /apps/nuqloud_world/api/activity
POST /apps/nuqloud_world/api/preferences
POST /apps/nuqloud_world/api/publish/prepare
POST /apps/nuqloud_world/api/publish/confirm

No public endpoints are required for MVP.

If a later public marketing preview is needed, it must be a separate static route with no user, file, identity, health, or service data.

Interface Modes

Existing NuQloud Surface

Purpose:

• Fast productivity.
• Full accessibility.
• Admin and heavy work.
• Default for existing users.

Implementation:

• Use the existing NuQloud/Nextcloud routes and surfaces.
• Do not create a competing dashboard route.
• NuQloud World may link back to these surfaces or open focused panels over them.

NuQloud World

Purpose:

• Branded spatial interface.
• Live service status.
• Contextual command panels.
• Optional immersive mode.

Route:

/apps/nuqloud_world/world

Compact Mobile

Purpose:

• Touch-first mobile use.
• Minimal animation.
• Fast loading.
• Optional or disabled Phaser scene.

Implementation:

• Same route as World Mode.
• Client selects compact shell based on viewport, user preference, reduced motion, and performance signals.

Visual Direction From Concepts

The screenshots establish the visual target:

• Dark command-shell foundation.
• Left-side navigation with clear active state.
• Dense but calm command content.
• Glassy panels with subtle borders.
• Blue primary actions.
• Green healthy/online signals.
• Purple or cyan for publishing/network highlights.
• Gold only for credit/plan emphasis.
• Large data visualization surfaces where useful.
• Side detail panels for Files, Talk, and status.
• Enterprise-grade language and layout discipline.

NuQloud World should reinterpret these as a spatial command layer:

• The concept globe/network becomes the central world backdrop.
• Files become a vault/storage island.
• Talk/private mail becomes a conversation sphere.
• Publishing/redundancy becomes a QDN portal and node map.
• Admin/status becomes an operations core.
• Cards become HTML overlay panels, not Phaser text-only UI.

Avoid:

• Cartoon game assets.
• RPG-style characters.
• Fake metaverse language.
• Canvas-only forms.
• Heavy 3D dependencies for MVP.
• One-off hardcoded colors instead of theme variables.

Product Language Modes

Default mode is Powered Mode.

Powered Mode language:

• Use NuQloud.
• Use QDN where protocol specificity is needed.
• Use Powered by Qortal where attribution is needed.
• Use credits for publishing capacity.
• Avoid wallet, coins, and QORT terminology.

Full Qortal Mode language:

• Crypto-native terminology is allowed.
• Qortal-specific labels may be shown.

Implementation rules:

• Never mix modes in the same view.
• All UI labels must come from translatable strings.
• Product mode must be read from server-side app config.
• Client-side mode is display-only and must not be trusted for authorization.

MVP World Layout

Initial service map:

                         QDN Portal

                             |

Talk / Private Mail -- NuQloud Core -- Files Vault

                             |

                          Deck Board

                             |

                       Admin / Status

MVP service nodes:

• NuQloud Core.
• Files Vault.
• Talk or Private Mail.
• Deck Board.
• QDN Portal.
• Admin / Status.

Each node needs:

• Stable id.
• Translated label.
• Translated description.
• Status.
• Badge count.
• Position.
• Icon or sprite key.
• Hover state.
• Click action.
• Activity pulse.
• HTML fallback action.

Example model:

type WorldServiceNode = {
  id: 'core' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin';
  labelKey: string;
  descriptionKey: string;
  status: 'healthy' | 'warning' | 'error' | 'unknown';
  badgeCount?: number;
  position: {
    x: number;
    y: number;
  };
  panel: 'overview' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin';
  requiredCapability?: string;
};

Panel Scope

Panels must be HTML/React components, not Phaser UI.

Overview Panel

MVP content:

• Instance name.
• Account display label.
• Overall health.
• Storage summary.
• Active apps summary.
• Recent activity.
• Current mode and World preference.

Files Panel

MVP content:

• Storage usage.
• Protected folder count.
• Recent files.
• Recent publish states if Files Bridge is installed.
• Open full Files link.
• Publish selected file action where authorized.

Talk Panel

MVP content:

• Unread count.
• Recent conversations.
• Relay or bridge state if Talk Bridge is installed.
• Open full Talk link.
• Message preview placeholder with no raw rendered user HTML.

Deck Panel

MVP content:

• Active tasks count.
• Recent tasks.
• Project links.
• Open full Deck link.
• Graceful unavailable state if the Deck surface is absent.

QDN Publish Panel

MVP content:

• Publish target.
• Selected file placeholder.
• Service/name/identifier fields.
• Server-side validation messages.
• Confirmation step.
• Pending/success/failure state.
• Receipt summary.

Admin / Status Panel

MVP content:

• Nextcloud status.
• QDN gateway status.
• Qortal node status where allowed by product mode and permissions.
• Talk backend status.
• Office backend status where configured.
• Redis status.
• Database status.
• Storage status.

Admin-only data must be withheld from non-admin users.

Event Architecture

Use a typed event bus between Phaser, React state, and API updates.

Event rule:

• Phaser sends UI intent.
• React/store sends state changes.
• API services execute actions.
• Phaser reacts visually to approved state.

Core events:

ui.openPanel
ui.closePanel
ui.focusService
ui.clearFocus
ui.setMode

service.statusChanged
service.badgeChanged
service.activityPulse
service.capabilityUnavailable

files.fileSelected
files.filePublished

talk.messageReceived
deck.taskUpdated

qdn.publishPrepared
qdn.publishStarted
qdn.publishCompleted
qdn.publishFailed

admin.healthChanged
preferences.updated

Example:

type WorldEvent =
  | {
      type: 'ui.openPanel';
      panel: 'overview' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin' | 'settings';
      context?: Record<string, unknown>;
    }
  | {
      type: 'service.statusChanged';
      serviceId: WorldServiceNode['id'];
      status: 'healthy' | 'warning' | 'error' | 'unknown';
    }
  | {
      type: 'qdn.publishCompleted';
      publishId: string;
      receiptUrl?: string;
    };

State Shape

type WorldState = {
  mode: 'existing' | 'world' | 'compact';
  productMode: 'powered' | 'full_qortal';
  user: {
    id: string;
    displayName: string;
    isAdmin: boolean;
  };
  instance: {
    name: string;
    baseUrl: string;
    status: 'healthy' | 'warning' | 'error' | 'unknown';
  };
  capabilities: Record<string, boolean>;
  services: WorldServiceNode[];
  badges: Record<string, number>;
  activity: WorldActivityItem[];
  preferences: {
    worldModeEnabled: boolean;
    reducedMotion: boolean;
    compactMode: boolean;
  };
};

Data Integration

Phase 1 uses fixtures only.

Phase 2 adds aggregated server state:

• Current user.
• Instance name.
• Storage used and quota.
• Recent files.
• Protected folders.
• Talk unread count.
• Recent conversations.
• Active Deck task count.
• Pending QDN publishes.
• Basic service health.
• Recent activity feed.

MVP update strategy:

• Poll service status every 30 to 60 seconds.
• Poll message/Deck task badges every 10 to 30 seconds.
• Poll storage every 60 to 300 seconds.
• Poll active publish jobs every 5 to 15 seconds.
• Add SSE or WebSocket only after the data model is stable.

Security Requirements

Mandatory rules:

• All product routes authenticated by default.
• All mutating API routes require CSRF protection.
• All publish actions require server-side authorization.
• All input must be validated and sanitized server-side.
• Do not trust node id, service id, file id, path, product mode, or permissions supplied by the client.
• Do not expose secrets, broker tokens, private node credentials, or internal service URLs to the browser.
• Do not render raw user input in panels, tooltips, activity feeds, or Phaser labels.
• Return capability-limited state for non-admin users.
• Define public endpoints separately before adding any.

QDN publish flow:

Client selects file
-> server verifies file access
-> server prepares publish request
-> user confirms in HTML panel
-> server submits publish action
-> server returns sanitized status/receipt
-> Phaser animates pending/success/failure

Accessibility Requirements

NuQloud World cannot be canvas-only.

Required:

• Every primary Phaser action also exists as an HTML button or navigation item.
• Keyboard navigation for service nodes and panels.
• ARIA labels on panels, dialogs, command controls, and status indicators.
• Focus trap for modal or side-panel workflows.
• Escape closes active panel.
• Reduced-motion preference.
• Compact/mobile fallback.
• Visible focus states using theme variables.
• No essential text rendered only inside Phaser.

Theming Requirements

Use Nextcloud and NuQloud theme variables:

• No hardcoded UI colors in components unless they are token definitions.
• Support dark first, with light mode compatibility later.
• Preserve concept accent roles:
  • blue for primary actions and selected navigation.
  • green for healthy/online/synced.
  • purple/cyan for publishing/network activity.
  • gold for credits or plan emphasis only.
• Keep panels responsive and mobile-first.
• Avoid nested card-heavy layouts in World overlays.

Performance Requirements

MVP targets:

• World route should feel immediate after auth.
• Mobile should default to compact or simplified mode.
• Idle CPU must stay low.
• Particle count must be capped.
• World assets must lazy-load.
• Animations pause or reduce when the tab is inactive.
• Reduced-motion mode disables non-essential animation.
• Texture assets should be optimized and bundled predictably.
• Avoid custom shaders in MVP unless a fallback exists.

Build Strategy

Recommended frontend:

• TypeScript.
• React.
• Phaser 4.
• Lightweight store such as Zustand or equivalent.
• Typed event bus.
• CSS tokens.

Recommended packaging:

• Build compiled assets into the Nextcloud app's js/ and css/ output.
• Keep the app loadable through normal Nextcloud script/style registration.
• Use Vite if it can emit Nextcloud-compatible static assets cleanly.
• Otherwise follow the repository's current app asset pipeline.

Do not require a standalone NuQloud frontend server for production.

Feature Flags

Server-side flags:

type NuQloudWorldFlags = {
  worldModeEnabled: boolean;
  worldModeDefault: boolean;
  worldModeBetaBadge: boolean;
  qdnPortalEnabled: boolean;
  deckNodeEnabled: boolean;
  talkNodeEnabled: boolean;
  filesNodeEnabled: boolean;
  adminStatusNodeEnabled: boolean;
  liveActivityEnabled: boolean;
  reducedMotionDefault: boolean;
};

Defaults:

• worldModeEnabled: false until beta.
• worldModeDefault: false until proven.
• qdnPortalEnabled: true only when integration is available.
• adminStatusNodeEnabled: visible to admins, limited for users.
• reducedMotionDefault: follow user/system preference.

Rollout Phases

Phase 0 - Design and Technical Lock

Deliverables:

• Confirm plugin app id.
• Confirm supported Nextcloud versions.
• Pin Phaser 4 version.
• Define service node list.
• Define panel list.
• Define event schema.
• Define API state contract.
• Define route map.
• Define theme tokens.
• Define feature flags.
• Define MVP acceptance criteria.
• Confirm language mode dictionary.

Exit criteria:

• No ambiguity about Phaser vs HTML responsibilities.
• No ambiguity about app/plugin boundaries.
• Implementation tickets can be created from this plan.

Phase 1 - Static Plugin Prototype

Build:

• New Nextcloud app shell.
• Authenticated /world route.
• Compiled TypeScript frontend bundle.
• Phaser boot scene.
• Static WorldScene.
• Five to six service nodes.
• Hover/focus/click effects.
• HTML overlay panel host.
• Mock panel content.
• Mock status badges.
• Reduced-motion toggle.

Exit criteria:

• /apps/nuqloud_world/world loads for authenticated users.
• Unauthenticated users cannot access it.
• Service nodes render.
• Hover, keyboard focus, and click open panels.
• Panels can open and close.
• No real publish action exists yet.

Phase 2 - State and Event Bus

Build:

• Typed event bus.
• World state store.
• Panel store.
• Service status store.
• Preference store.
• Mock activity events.
• Phaser subscriptions to store updates.
• HTML command bar fallback.

Exit criteria:

• Phaser does not own business logic.
• State updates affect both panels and scene objects.
• All primary actions work without clicking the canvas.
• Mock activity pulses work.

Phase 3 - Aggregated Server State

Build:

• WorldStateController.
• WorldStateService.
• Integration services for installed NuQloud apps.
• Capability detection.
• Sanitized JSON state endpoint.
• Loading/error/offline states.
• Basic polling.

Exit criteria:

• Real counts show where integrations are installed.
• Missing integrations degrade gracefully.
• Non-admin users do not receive admin-only data.
• API errors render cleanly.

Phase 4 - QDN Portal MVP

Build:

• Select file from Files panel.
• Prepare publish request server-side.
• Confirmation panel.
• Submit publish action server-side.
• Pending state.
• Success/failure receipt.
• Phaser portal animations based on approved server state.

Exit criteria:

• No destructive or publishing action happens without confirmation.
• Invalid file ids, paths, names, services, and identifiers are rejected.
• Publish status is visible in both panel and world node.
• Errors expose no secrets.

Phase 5 - Useful Spatial Workflows

Build one workflow that makes the theme layer useful beyond visual polish:

• Conversation/project room.
• Linked files.
• Linked Deck tasks.
• QDN publish history.
• Activity timeline.
• Open object -> real panel/detail view.

Exit criteria:

• A user can move from conversation/project context to files/Deck/publishing without losing context.
• Spatial view is not decorative only.

Phase 6 - Mobile and Accessibility Hardening

Build:

• Compact shell.
• Touch-safe controls.
• Keyboard navigation pass.
• ARIA audit.
• Reduced-motion pass.
• Performance budget pass.
• Cross-browser sanity pass.

Exit criteria:

• Mobile users are not forced into heavy world mode.
• All core actions work without Phaser.
• Focus order is understandable.
• Reduced motion meaningfully reduces animation.

Phase 7 - Private Beta

Rollout:

• Enable behind feature flag.
• Default users to existing NuQloud surfaces.
• Allow opt-in to World Mode.
• Collect feedback.
• Track performance and usage.

Metrics:

• World Mode activation rate.
• Repeat usage.
• Time to first useful action.
• Panel open counts.
• Publish completion rate.
• API failure rate.
• Slow load rate.
• Mobile fallback usage.

Exit criteria:

• Users understand the interface.
• Performance is acceptable.
• No major accessibility blocker remains.
• World Mode creates clear product differentiation.

Phase 8 - Public Launch Readiness

Build:

• Final branded art assets.
• Polished animations.
• Preference setting.
• Admin controls.
• Documentation.
• Marketing screenshots/video.
• Upgrade notes.

Exit criteria:

• App can ship without a Nextcloud fork.
• Feature flags support rollback.
• Admins can disable World Mode.
• Documentation explains existing, world, and compact modes.

Implementation Tickets

Foundation

• Create nuqloud_world app scaffold.
• Add authenticated page controller.
• Add route registration.
• Add frontend build pipeline.
• Add feature flag service.
• Add world preference storage.

Frontend Shell

• Add React app shell.
• Add Phaser game mount/unmount lifecycle.
• Add overlay layer.
• Add panel host.
• Add command bar.
• Add compact shell.
• Add theme token file.
• Add i18n files.

Phaser Layer

• Add BootScene.
• Add PreloadScene.
• Add WorldScene.
• Add EffectsScene.
• Add ServiceNode object.
• Add FilesVault object.
• Add TalkSphere object.
• Add DeckBoard object.
• Add QdnPortal object.
• Add AdminCore object.
• Add reduced-motion behavior.

State and Events

• Add typed world event definitions.
• Add world bus.
• Add world store.
• Add service status store.
• Add panel store.
• Add preference store.
• Add mock event generator for prototype only.

API and Services

• Add state endpoint.
• Add service capability endpoint.
• Add activity endpoint.
• Add preferences endpoint.
• Add publish prepare endpoint.
• Add publish confirm endpoint.
• Add integration adapters for core, Files Bridge, Talk Bridge, and QDN.

Panels

• Add Overview panel.
• Add Files panel.
• Add Talk panel.
• Add Deck panel.
• Add QDN Publish panel.
• Add Admin Status panel.
• Add Settings panel.
• Add unavailable integration state.

Security

• Add CSRF coverage for mutating endpoints.
• Add server-side authorization checks.
• Add input validation helpers.
• Add output sanitization policy.
• Add permission-limited state shaping.
• Add admin-only status filtering.

Accessibility

• Add keyboard node navigation.
• Add HTML action equivalents.
• Add ARIA labels and roles.
• Add focus management.
• Add reduced-motion toggle.
• Add compact fallback.

QA and Release

• Add unit tests for services and validation.
• Add frontend tests for event/store behavior.
• Add route/auth tests.
• Add manual devcloud verification steps.
• Add beta flag rollout docs.
• Add rollback docs.

Acceptance Criteria

MVP is complete when:

• World Mode is delivered as a theme-grade Nextcloud app/plugin.
• No Nextcloud fork is required.
• Route is authenticated.
• All mutating actions are CSRF protected.
• No raw user input is rendered.
• Service nodes and HTML fallback actions match.
• Panels use translated strings.
• Product language mode is consistent per view.
• Core state loads from a server endpoint.
• Missing integrations degrade gracefully.
• QDN publish workflow requires confirmation.
• Reduced-motion and compact modes exist.
• Admin-only state is not exposed to regular users.

Devcloud Verification Commands

Use devcloud only. Do not run local Docker/Nextcloud for this work.

Example commands once implementation begins:

docker compose --env-file .env.devcloud exec nextcloud php occ app:list
docker compose --env-file .env.devcloud exec nextcloud php occ app:enable nuqloud_world
docker compose --env-file .env.devcloud exec nextcloud php occ app:check-code nuqloud_world
docker compose --env-file .env.devcloud exec nextcloud php occ config:app:get nuqloud_world worldModeEnabled
docker compose --env-file .env.devcloud exec nextcloud php occ maintenance:repair --include-expensive

Frontend build verification, from the app directory:

npm ci
npm run build
npm test -- --run

Verify-by-Inspection Checklist

• App structure valid: appinfo/, routes.php, controllers, services.
• Auth enforced on all product routes.
• Public endpoints explicitly absent or separately documented.
• CSRF enforced on all mutating endpoints.
• No raw user input rendered.
• No secrets exposed to logs or client state.
• Imports and exports consistent.
• i18n used for UI labels.
• Theme variables used instead of hardcoded component colors.
• Product language mode not mixed in a view.
• CHD admin surfaces not exposed.
• Nextcloud version compatibility checked in Phase 0.
• Mobile and reduced-motion fallbacks included.