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.

Status: Design phase. Nothing in this directory is implemented yet. These documents define the target architecture; they will be revised as we prototype.

---

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	This file
01	01-overview.md	Goals, non-goals, success metrics, WeChat parallels
02	02-architecture.md	System layers and data flow
03	03-host-contract.md	BasedMiniAppHost Dart interface
04	04-manifest.md	based.json manifest schema
05	05-js-runtime.md	QuickJS runtime, isolates, lifecycle
06	06-bridge-and-codegen.md	Dart↔JS bridge protocol
07	07-ui-nodes-and-renderer.md	UiNode tree and widget catalog
08	08-security-and-sandbox.md	Threat model and sandbox guarantees
09	09-distribution-and-updates.md	Bundles, CDN, signing, kill switch
10	10-developer-experience.md	CLI, templates, simulator, docs site
11	11-roadmap-and-milestones.md	Phased plan and risk register
12	12-open-questions.md	Unresolved decisions and decision log
13	13-changelog.md	Partner-facing SDK changelog
14	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 as a numbered entry; resolved entries are moved to the relevant doc and crossed out in the decision log.