# 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.