> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/mini-apps-platform.md).

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