simon/qortal-web-builder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
qortal-web-builder/README.md
T
Simon James e82af8b9bb Add README explaining QWB, Qortal Web, and Q-Shops
2026-06-09 12:31:40 +00:00

299 lines
14 KiB
Markdown
Raw Permalink Blame History

# Qortal Web Builder
A monorepo of **Q-Apps** for the [Qortal](https://github.com/qortal) ecosystem — decentralized websites and commerce on the **Qortal Data Network (QDN)**, loaded through the **Qortal Hub**.
This repository contains three related applications that share one core codebase:
| App | Folder | Role |
|-----|--------|------|
| **Qortal Web Builder (QWB)** | repo root (`src/`) | Visual editor — build and publish websites to QDN |
| **Qortal Web** | `qortal-web-app/` | Public discovery engine — browse everything QWB publishes |
| **Q-Shops** | `q-shops-app/` | Marketplace aggregator — browse and buy from many Q-Shops at once |
All three run as **static Q-Apps**: a zip of HTML, JS, CSS, and assets that the Hub loads locally. Blockchain and QDN access go through **`qortalRequest`** (the Hub bridge), not a custom backend server.
---
## How the three apps fit together
```
┌─────────────────────────────────────────────────────────────────┐
│ Qortal Web Builder (QWB) │
│ You design blocks → publish WEBSITE + QDN resources │
└───────────────┬─────────────────────────────┬───────────────────┘
│ │
▼ ▼
┌────────────────────────┐ ┌──────────────────────────────┐
│ Published WEBSITE │ │ Qortal Web index DOCUMENT │
│ (visitor-facing site) │ │ (.__qwb__/qortal-web-index) │
└────────────────────────┘ └──────────────┬───────────────┘
│
▼
┌────────────────────────────────┐
│ Qortal Web │
│ Search · Discover · Open │
└────────────────────────────────┘
QWB Q-Shop block ──► catalog manifest on QDN ──► Q-Shops app
(per-shop + optional directory snapshot)
```
- **QWB** is where sites are **created and published**.
- **Qortal Web** reads **index files** that QWB publishes alongside each site, then lets anyone **search and open** websites, forums, articles, media, folders, and more.
- **Q-Shops** reads **Q-Shop catalog manifests** from many publishers and presents a **unified marketplace** with cart, checkout, and order history.
---
## Qortal Web Builder (QWB)
**What it is:** A Mobirise-style **block editor** for Qortal. You compose a site from draggable blocks, tune themes and pages, then publish to QDN as a **WEBSITE** resource (and related DOCUMENT/JSON payloads).
**Who it is for:** Site owners, creators, and merchants who want a full website on Qortal without writing code.
### Core workflow
1. **Open QWB** in the Qortal Hub (load the Q-App zip).
2. **Authenticate** with your Qortal wallet so publishes are signed on-chain.
3. **Add blocks** from the block library — header, hero, text, galleries, interactive blocks, etc.
4. **Configure** pages, navigation, themes, and per-block options in the inspector.
5. **Save a draft** locally (browser) and/or to QDN as a DOCUMENT.
6. **Publish Website** — builds a `website.zip`, uploads WEBSITE + peer JSON (forum, poll, comments), Q-Shops index, and the **Qortal Web index** when applicable.
Published sites are **static SPAs** with a visitor runtime: guests browse freely; **Authenticate** unlocks posting, voting, checkout, and other wallet-gated actions.
### Block types
**Layout & content**
| Block | Purpose |
|-------|---------|
| Banner | Rotating announcement bar |
| Header | Logo, site title, main navigation |
| Hero | Title, intro, call-to-action |
| Countdown | Timer with on-complete actions |
| Text | Rich text (headings, links, embedded media) |
| Buttons | Linked buttons (`qortal://`, external URLs) |
| Multi-column | Image + heading + description grids with section CTA |
| Photo | Single image, fullscreen viewer |
| Albums | Photo galleries with layouts and lightbox |
| Video | Upload or Q-Tube embed |
| Music | Albums and on-page player (Q-Music integration) |
| Map pins | Map with coordinate pins and photos |
| Q-Apps | Embed other Q-Apps in tabs or a grid |
| Links | Quick link list |
| Footer | Credits and footer links |
**Interactive & commerce** (data stored on QDN as signed JSON / resources)
| Block | Purpose |
|-------|---------|
| Comments | Visitor comments with moderation |
| Forum | Topics, replies, votes, archiving |
| Vote / poll | Polls with eligibility rules and on-chain-style votes |
| Folders | File library — publish to Q-Share, Q-Tube, Q-Music; PDF/image viewers |
| Q-Shop | Full storefront — catalog, cart, checkout, digital downloads, merchant tools |
| Newsletter | Q-Mail subscriber list and campaigns |
| Contact form | Encrypted Q-Mail to the site owner |
| Groups | Join a Qortal group; live member count |
| Articles | Long-form articles with Q-Blog sync and comment threads |
### Publishing & access control
- **Global** sites are listed on **Qortal Web** for everyone.
- **Group-only** sites restrict the published WEBSITE to members of a chosen Qortal group; Qortal Web shows them only to authenticated group members (index carries `websiteAccessMode` + `websiteAccessGroupId`).
- **Discover listing** can be toggled per site; QWB writes a **Qortal Web index** DOCUMENT (`.__qwb__/qortal-web-index.json`) so Qortal Web can index forums, polls, articles, media, folders, and the site itself.
### Q-Shop inside QWB
The Q-Shop block is a complete storefront: categories, variants, coupons, shipping vs pickup vs digital, QORT / Q-Asset payments via Hub, order invoices, and merchant ledger tools. Catalog data is published to QDN so **Q-Shops** (and Qortal Web) can discover it.
### Technical notes
- Source: `src/`, entry `dev.html` (builder), `site.html` (published visitor preview path).
- State: Zustand (`src/store/builderStore.ts`); drafts in `localStorage` + optional QDN DOCUMENT.
- Hub API: `src/lib/qortalClient.ts` → `qortalRequest` actions (`PUBLISH_QDN_RESOURCE`, `SEARCH_QDN_RESOURCES`, etc.).
- See **[QORTAL-HUB.md](./QORTAL-HUB.md)** for zip layout, WEBSITE vs APP routing, auth troubleshooting, and grey-screen fixes.
**Build & release zip**
```bash
npm install
npm run build
bash scripts/zip-portfolio.sh # → Portfolio-Q-App-v3-YYYYMMDD.zip
```
---
## Qortal Web
**What it is:** The **Qortal Web Engine** — a discovery and search front-end for content published through QWB. It scans QDN for QWB index DOCUMENTs, merges them into a searchable catalog, and lets users browse by category or query.
**Who it is for:** Anyone exploring the Qortal web — finding websites, reading articles, opening forums, watching indexed videos, browsing shared folders, etc.
### What it indexes
Each QWB site can publish a structured index (`qortal-web-index-v1`) listing entries such as:
- **website** — the site itself (title, logo, preview image)
- **forum**, **poll**, **article** — interactive blocks (opens in embedded published-site viewers)
- **video**, **music**, **photo**, **albums** — media blocks
- **folder**, **library** — Share Folders / file listings
- **qshop** — linked storefront catalog entries
### Main features
- **Home** — stats, top publishers, discover website cards, global search.
- **Category browse** — filter by content kind (websites, forums, articles, video, music, folders, etc.).
- **Search** — full-text search across indexed titles and descriptions.
- **Content viewer** — opens the target in-context: full site embed for websites, hybrid block-focus embeds for forum/poll/article (real published visitor runtime), native media viewers where appropriate.
- **Authenticate** — Hub wallet sign-in for group-gated sites, masthead identity, and interactive embeds that need a session.
- **Group-only visibility** — sites published as group-only appear only if the signed-in account is a member of that group.
- **Open in Qortal** — jump to `/render/WEBSITE/{publisher}` in the Hub.
Qortal Web **imports shared code from QWB** (`@qwb/core`, `@qwb/visitor`) via Vite aliases — it is not a standalone package; clone and build from this monorepo root.
**Build & release zip**
```bash
npm install # root deps (shared with QWB)
npm --prefix qortal-web-app install
npm --prefix qortal-web-app run build
bash scripts/zip-qortal-web-app.sh # → Qortal-Web-v0.0.29-YYYYMMDD.zip
```
---
## Q-Shops
**What it is:** A **marketplace aggregator Q-App** that collects **Q-Shop catalogs** published by QWB sites across QDN and presents them in one unified UI — browse many shops, add to cart across vendors, checkout with Hub payments, and track orders.
**Who it is for:** Buyers who want one place to shop all Qortal Web Builder stores; complements the per-site Q-Shop block on individual websites.
### How discovery works
1. QWB site owners publish a **Q-Shop block** and include catalog manifests on QDN (`qwb-qshops-catalog-v1` and related DOCUMENTs).
2. Q-Shops **searches QDN** for these manifests and merges them into a live directory.
3. Optional **directory snapshots** (`qshops-directory-snapshot-v1`) from curators federate listings when SEARCH alone is sparse on a given Hub node.
4. The catalog **refreshes periodically** and when you return to the tab so prices, stock, and new shops stay current.
### Main features
- **Marketplace browse** — grid and list views, category filters, shop gallery with hero imagery.
- **Product detail** — variants, gallery, shipping/digital tabs, quick add.
- **Multi-vendor cart** — line items grouped by shop; checkout per vendor or combined flow.
- **Checkout** — shipping vs pickup vs digital-only; delivery map (Leaflet + bundled tiles); encrypted **buyer profile on QDN** (same identifier family as QWB checkout).
- **Payments** — `SEND_COIN` / Q-Asset transfer via Hub; payment overlay designed so Hub signer dialogs are not blocked by the Q-App UI.
- **Q-Mail receipts** — seller notification and buyer receipt after successful payment.
- **Digital goods** — download `qortal://FILE/…` products after payment.
- **My orders** — persisted per wallet; invoices with re-download for digital lines.
- **Authenticate** — required for checkout, saved shipping, and order history.
**Build & release zip**
```bash
npm install
npm --prefix q-shops-app install
npm --prefix q-shops-app run build
bash scripts/zip-q-shops-app.sh # → Q-Shops-v0.0.45-YYYYMMDD.zip
```
---
## Repository layout
```
qortal-web-builder/
├── src/ # QWB application source (builder + published block views)
├── packages/qwb-visitor/ # Shared visitor runtime (used by QWB, Qortal Web, embeds)
├── qortal-web-app/ # Qortal Web Q-App
├── q-shops-app/ # Q-Shops Q-App
├── scripts/ # Build, sync dist, zip helpers
├── public/ # Static assets shipped with QWB
├── dev.html # QWB Vite dev/build entry (builder UI)
├── site.html # Published visitor site entry (export path)
├── QORTAL-HUB.md # Hub deployment & troubleshooting
└── CHANGELOG.md # QWB release notes
```
**Not in git** (see `.gitignore`): `node_modules/`, `dist/`, `extracted/`, release `*.zip` files, generated root `index.html` / `assets/` (produced by `npm run build`).
---
## Getting started (developers)
### Prerequisites
- [Node.js](https://nodejs.org/) 18+ (LTS recommended)
- [Qortal Hub](https://github.com/Qortal/Qortal-Hub) for testing Q-Apps with a real `qortalRequest` bridge
### Install
```bash
git clone https://gitea.qortal.link/simon/qortal-web-builder.git
cd qortal-web-builder
npm install
npm --prefix qortal-web-app install
npm --prefix q-shops-app install
```
### Local development (optional)
Q-Apps are meant to run **inside the Hub**. Local Vite dev servers are useful for UI work but **cannot** complete wallet auth without the bridge:
```bash
npm run dev # QWB builder → dev.html
npm --prefix qortal-web-app run dev # Qortal Web
npm --prefix q-shops-app run dev # Q-Shops
```
For real QDN testing, always **build + zip + load in Hub Preview**.
### Release zips (summary)
| App | Command |
|-----|---------|
| QWB | `npm run build && bash scripts/zip-portfolio.sh` |
| Qortal Web | `bash scripts/zip-qortal-web-app.sh` |
| Q-Shops | `bash scripts/zip-q-shops-app.sh` |
Zip contents must be **flat** (files at archive root: `index.html`, `assets/`, `manifest.json`, …). See [QORTAL-HUB.md](./QORTAL-HUB.md).
---
## QDN & Hub concepts (short glossary)
| Term | Meaning |
|------|---------|
| **QDN** | Qortal Data Network — on-chain storage for DOCUMENT, WEBSITE, IMAGE, JSON, etc. |
| **Q-App** | Static app package (zip) registered and loaded by the Hub |
| **WEBSITE** | Published site zip — visitor-facing pages |
| **DOCUMENT** | JSON or text resource (drafts, indexes, manifests) |
| **qortalRequest** | JavaScript API injected by the Hub for wallet + QDN operations |
| **Registered name** | Human-readable Qortal identity tied to an address (used for publishing and avatars) |
Official references: [Q-Apps.md](https://github.com/Qortal/qortal/blob/master/Q-Apps.md), [qortal.dev Q-Apps](https://qortal.dev/docs/q-apps), [Qortal API docs](https://api.qortal.org/api-documentation/).
---
## Contributing & version control
Changes are **not** pushed to Gitea automatically. After editing:
```bash
git add -A
git commit -m "Describe your change"
git push
```
Changelogs:
- QWB — `CHANGELOG.md`
- Qortal Web — `qortal-web-app/CHANGELOG.md`
- Q-Shops — `q-shops-app/CHANGELOG.md`
---
## License
No license file is included yet. Add one in Gitea if you intend to open-source or clarify usage terms.
Reference in New Issue View Git Blame Copy Permalink