# Mobile Mini Apps Architectural design docs for the **Based Mini-Apps** platform — a sandboxed, JS-runtime-based mini-app system embedded in the Based Super App, modeled loosely on WeChat Mini-Programs. {% hint style="info" %} **Status:** Design phase. Nothing in this directory is implemented yet. These documents define the target architecture; they will be revised as we prototype. {% endhint %} *** ## Why this exists The Based app is a multi-tenant crypto super-app (trading, prediction markets, credit cards, e-commerce). To scale beyond first-party features without inflating the binary, slowing review cycles, or coupling partner code to our internals, we need a way for **third-party developers and internal feature teams to ship sandboxed UI experiences that run inside the host app**. We chose **Option C — Embedded JS Runtime** (over server-driven UI and compile-time modules) because the long-term north star is a WeChat-style ecosystem: dozens of independent mini-apps, partner-built, hot-updatable, sandboxed, against a stable API surface that we control. *** ## Reading order If you're new to this project, read in this order. Earlier docs are prerequisites for later ones. | # | Doc | What it covers | | -- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | 00 | [README.md](/docs/integrations/mini-apps-platform.md) | This file | | 01 | [01-overview.md](/docs/integrations/mini-apps-platform/01-overview.md) | Goals, non-goals, success metrics, WeChat parallels | | 02 | [02-architecture.md](/docs/integrations/mini-apps-platform/02-architecture.md) | System layers and data flow | | 03 | [03-host-contract.md](/docs/integrations/mini-apps-platform/03-host-contract.md) | `BasedMiniAppHost` Dart interface | | 04 | [04-manifest.md](/docs/integrations/mini-apps-platform/04-manifest.md) | `based.json` manifest schema | | 05 | [05-js-runtime.md](/docs/integrations/mini-apps-platform/05-js-runtime.md) | QuickJS runtime, isolates, lifecycle | | 06 | [06-bridge-and-codegen.md](/docs/integrations/mini-apps-platform/06-bridge-and-codegen.md) | Dart↔JS bridge protocol | | 07 | [07-ui-nodes-and-renderer.md](/docs/integrations/mini-apps-platform/07-ui-nodes-and-renderer.md) | `UiNode` tree and widget catalog | | 08 | [08-security-and-sandbox.md](/docs/integrations/mini-apps-platform/08-security-and-sandbox.md) | Threat model and sandbox guarantees | | 09 | [09-distribution-and-updates.md](/docs/integrations/mini-apps-platform/09-distribution-and-updates.md) | Bundles, CDN, signing, kill switch | | 10 | [10-developer-experience.md](/docs/integrations/mini-apps-platform/10-developer-experience.md) | CLI, templates, simulator, docs site | | 11 | [11-roadmap-and-milestones.md](/docs/integrations/mini-apps-platform/11-roadmap-and-milestones.md) | Phased plan and risk register | | 12 | [12-open-questions.md](/docs/integrations/mini-apps-platform/12-open-questions.md) | Unresolved decisions and decision log | | 13 | [13-changelog.md](/docs/integrations/mini-apps-platform/13-changelog.md) | Partner-facing SDK changelog | | 14 | [14-breaking-change-policy.md](/docs/integrations/mini-apps-platform/14-breaking-change-policy.md) | Semver and deprecation policy | *** ## Glossary * **Host app** — the Based super-app binary (`flutter/based_app/`). Owns auth, signing, networking, native APIs. * **Mini-app** — a third-party or first-party UI experience packaged as a JS bundle + manifest, executed inside the host. Sandboxed. * **Host contract** (`BasedMiniAppHost`) — the Dart interface that defines every native capability a mini-app can request. Equivalent of WeChat's `wx.*`. * **Bridge** — the Dart↔JS message channel that exposes `BasedMiniAppHost` to mini-app code as a `based.*` global. * **Manifest** (`based.json`) — declarative metadata for a mini-app: id, version, permissions, entry point, theme overrides. * **UiNode** — the renderable tree shape produced by mini-app code. Rendered natively by host using `based_ui` widgets. * **Bundle** — the deployable artifact: `main.js` + `based.json` + assets, signed and distributed via CDN. * **`based_ui`** — the host's shared widget library (extracted from `flutter/based_app/lib/presentation/widgets/common/`). Mini-apps render against this via `UiNode`. * **`based_mini_app_sdk`** — the Dart package that defines the host contract, manifest parser, and permission enforcer. * **`based_js_runtime`** — the Dart package that wraps the JS engine and runs mini-app bundles. *** ## Out of scope (for the design phase) These are deliberately deferred until after the first runnable prototype: * Mini-app marketplace / discovery UX * Revenue share / billing * Partner onboarding and review workflows * Localization tooling for partner mini-apps * Native module extension API (mini-apps calling custom platform code) *** ## How to contribute to these docs 1. Each doc owns a **Status** banner at the top: `Draft`, `Reviewed`, `Approved`. 2. Substantive changes to an `Approved` doc require a PR with at least one reviewer from the platform team. 3. Cross-cutting decisions go in [`12-open-questions.md`](/docs/integrations/mini-apps-platform/12-open-questions.md) as a numbered entry; resolved entries are moved to the relevant doc and crossed out in the decision log. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://basedapp.gitbook.io/docs/integrations/mini-apps-platform.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.