q-tube/QORTAL.md

Architecture Overview

qapp-core is a React component library for building Qortal decentralized applications (q-apps). It provides hooks, components, and utilities for interacting with the Qortal Data Network (QDN).

Global State Pattern

The library uses Zustand stores in src/state/ for internal state management:

• publishes.ts - Resource download status tracking, peer info, caching
• cache.ts - Search results and resource data caching with TTL expiry
• lists.ts - List pagination state
• auth.ts - Authentication state

The GlobalProvider in src/context/GlobalProvider.tsx is the main entry point. Apps wrap their root with it, passing appName and publicSalt config. It wires up:

• Authentication (useAuth)
• Resource management (useResources)
• Persistent storage (usePersistentStore)
• Index management (useIndexes)

QDN Resource Flow

Resources on QDN are identified by {service, name, identifier}. The typical flow:

1. useResources or ResourceListDisplay components search/list metadata
2. useResourceStatus tracks download progress from peers
3. Resources are fetched via qortalRequest() - a global injected by the Qortal browser

Global Type Augmentation

src/global.ts declares the global qortalRequest() function and QortalRequestOptions union type. This provides TypeScript support for the ~100+ Qortal API actions. The types are in src/types/qortalRequests/interfaces.ts.

Build Output

tsup bundles to ESM/CJS with externalized React/MUI peer deps. Type declarations are generated separately via tsc. The global.d.ts export provides ambient types for consumers.

i18n

Locale JSON files in src/i18n/locales/{lang}/ are compiled into a single compiled-i18n.json at build time. Add translations there, then run npm run generate-i18n.

Key Exports

• GlobalProvider, useGlobal - Context setup and access
• usePublish, useResources, useResourceStatus - QDN resource operations
• ResourceListDisplay, ResourceListPreloadedDisplay - List rendering components
• VideoPlayer, AudioPlayerControls - Media components with QDN integration
• addAndEncryptSymmetricKeys, decryptWithSymmetricKeys - Encryption utilities
• EnumCollisionStrength, hashWordWithoutPublicSalt - Identifier hashing for privacy