mirror of
https://github.com/Qortal/q-tube.git
synced 2026-07-29 05:26:13 +00:00
Qortal Seth
31e16f4089
Updated dependencies Changed search API call in usePlaylistManagement.tsx into a qortalRequest() Added CONTEXT.md and QORTAL.md for AI agents. Optimized imports across src directory
46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
## 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
|