> 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/11-roadmap-and-milestones.md).

# Roadmap & milestones

A phased plan to get from "nothing" to a partner-shippable v1, then to a third-party-ready platform. Numbers are estimates, not commitments; they assume a 2–3 person platform team plus support from feature teams as called out.

## High-level shape

```mermaid
flowchart LR
    P0["Phase 0<br/>Workspace prep<br/>2 weeks"]
    P1["Phase 1<br/>Foundation packages<br/>4–6 weeks"]
    P2["Phase 2<br/>Runtime &amp; bridge<br/>8–10 weeks"]
    P3["Phase 3<br/>First-party mini-app<br/>4–6 weeks"]
    P4["Phase 4<br/>Partner pilot<br/>~3 months"]
    P5["Phase 5<br/>External GA<br/>~3 months"]
    P0 --> P1 --> P2 --> P3 --> P4 --> P5
```

Total to GA: \~9–12 months, depending on partner pilot velocity and how much of the host work overlaps with the broader Flutter migration.

***

## Phase 0 — Workspace prep (2 weeks)

**Goal:** convert `flutter/based_app/` into a melos workspace with one package, no behavior change, CI green.

### Tasks

* Set up `melos.yaml`; move `based_app` under `flutter/based_app/` (already there).
* Add `packages/` directory with empty package skeletons: `based_ui`, `based_core`, `based_mini_app_sdk`, `based_js_runtime`, `based_ui_nodes`.
* Configure shared `analysis_options.yaml`, `dart_test.yaml`, build\_runner config.
* Update CI to run `melos bootstrap`, `melos test`, `melos analyze`.
* Update `make run-based`, `make run-hyena`, `make build-*` to work under melos.

### Exit criteria

* All existing tests pass.
* `make run-based` and `make run-hyena` still work.
* `flutter test` runs across all packages via `melos test`.

### Risks

* Code generation paths (`build.yaml`) must be moved/updated. Tracked in MEMORY.md.
* Tenant flavor build steps may need adjustment.

***

## Phase 1 — Foundation packages (4–6 weeks)

**Goal:** extract `based_ui` and `based_core` from the host app, with no v1 mini-app code yet.

### `based_ui` (3 weeks)

* Move `presentation/widgets/common/*` to `packages/based_ui/lib/`.
* Move `theme/app_colors.dart`, `theme/app_theme.dart`, `theme/design_system.dart` to `packages/based_ui/lib/theme/`.
* Make tenant theme an injected dependency, not an internal Riverpod read. The `based_ui` package must build standalone without Riverpod.
* Set up `widgetbook` in `packages/based_ui/example/` for live previews.
* Migrate host imports.

### `based_core` (2 weeks)

* Extract networking (Dio interceptors, error types, response models).
* Extract storage abstractions (MMKV wrapper, key namespacing).
* Extract logging.
* `ActiveSignerService` stays in host app for now (it's tied to the wallet; we'll wrap it for `BasedSigning` later in phase 2).

### Exit criteria

* `based_app` depends on `based_ui` and `based_core` instead of internal paths.
* `widgetbook` boots locally and shows ≥ 80% of common widgets.
* No regression in tests.
* Snapshot tests for top-10 most-used widgets across both tenants.

### Risks

* Decoupling `based_ui` from Riverpod may surface widgets that secretly read providers — surfacing is expected, refactoring is a one-time cost.
* Decoupling theme from the active tenant widget tree means a per-tenant `Theme` boundary; we already have this via `app.dart`.

***

## Phase 2 — Runtime and bridge (8–10 weeks)

**Goal:** runnable JS mini-apps in a debug build of the host. No partner audience yet; this is internal validation.

### Tracks (parallelizable)

#### Track A — `based_mini_app_sdk` (4 weeks)

* Define the `BasedMiniAppHost` Dart interface and all sub-interfaces.
* Manifest parser + JSON schema.
* Permission enforcer.
* Compat-shim framework (empty for now).
* Stub implementations for testing.

#### Track B — `based_js_runtime` (6 weeks)

* Integrate `flutter_js` (QuickJS).
* Per-mini-app isolate spawn + lifecycle.
* Bridge transport (`SendPort` pair, JSON encoding).
* CPU watchdog (interrupt callback).
* Heap and bundle size limits.
* `console.*` redirection, error capture.
* Pre-warmed isolate pool.

#### Track C — Bridge codegen (3 weeks; starts in week 3)

* `tools/bridge_codegen/` build\_runner generator.
* Generates: Dart dispatcher table, JS shim, JSON schema, TS declarations.
* Wired into CI; PRs that change the interface without regenerating fail.

#### Track D — `based_ui_nodes` + renderer (4 weeks)

* `UiNode` freezed type.
* Catalog implementations mapping each `type` to a `based_ui` widget.
* Renderer with diffing.
* Event ref system (handles, GC).
* Reactive primitive (signal/computed) — small, \~200 LOC.

### Exit criteria

* A handwritten "hello world" JS bundle boots in a debug host build, renders a screen with a button, clicking the button shows a host-rendered toast via `based.ui.toast`.
* A second test bundle exercises `based.signing.signMessage` against a test wallet, and the confirmation sheet renders correctly with the manifest's name and reason.
* `based.http.get` round-trips with permission allowlist enforced (call with disallowed domain rejects with stable error code).
* Memory + CPU watchdogs verified by intentionally-pathological test bundles.

### Risks

* `flutter_js` + isolates: there may be platform-channel quirks getting QuickJS to run in a non-main isolate. Plan a 1-week spike at the start of track B to de-risk.
* Codegen complexity: generating both Dart, JSON schema, and TS from one source needs care. Start with manual hand-written for one method, then generalize.

***

## Phase 3 — First-party mini-app pilot (4–6 weeks)

**Goal:** ship one real first-party feature as a mini-app inside the production host (behind a feature flag).

### Pick the right mini-app

Selection criteria:

* Must be self-contained (no live websocket; no chained signing flows).
* Must be visible enough to learn from real usage.
* Must be backed by an internal team that can re-author the feature in TS.

Candidate features ranked:

| Candidate                        | Verdict                                                 |
| -------------------------------- | ------------------------------------------------------- |
| `referral` (refer-a-friend flow) | ✅ Best — self-contained, low traffic, low risk.         |
| `shop` cart/checkout             | ⚠️ Possible — depends on commerce APIs already in host. |
| Promo / "earn" landing pages     | ✅ Excellent — content-heavy, lightweight signing.       |
| `trade`                          | ❌ Worst — websockets, real-time data, complex state.    |
| `predict`                        | ❌ Bad — same reasons as trade.                          |

**Recommendation: start with promo/earn-style mini-apps**, then graduate to `referral`.

### Tasks

* Re-author the chosen feature as a mini-app in TS.
* Stand up the internal CDN endpoint and a stub registry index.
* Implement on-demand install and cold-boot timing in the host.
* Behind feature flag, route the chosen feature through the mini-app path; keep the native version available as fallback.

### Exit criteria

* The mini-app is in production, behind a flag.
* A/B telemetry between native and mini-app paths shows: parity in conversion, p95 boot < 800ms (cached), error rate within 2× of native.
* Internal team is willing to re-author a second feature.

### Risks

* "Native vs mini-app" parity is harder than it sounds. Expect 2 weeks of polishing animation/layout edge cases.
* The internal team may discover catalog gaps. Catalog additions go through the same review as third-party requests but with faster turnaround.

### Status

Phase 3 has shipped end-to-end as of the 2026-04 / 2026-05 batch:

* Two production mini-apps live in the home-screen carousel: **Pull.Fun** (gacha), **AI Assistant** (chat + billing). Both partner-hosted; bundles fetched from CDN at runtime, no host rebuild required to ship updates.
* Generic launch route `/mini-apps/launch?manifest=<url>` replaced the per-mini-app routes — the host derives the bundle URL from the manifest's `entry` field.
* Whitelisted registry (`mini_app_registry.dart`) drives the home carousel; "Open by URL" sheet handles power-user / partner-dev launches.
* Auto-hiding drag-to-dismiss grabber (iOS modal idiom) gives users a discoverable exit on every mini-app surface.
* Notifications surface (Phases 1–3) shipped: local push via `based.notifications.show`, partner-mediated remote push via the gateway, iOS Live Activities + Android Live Updates with a templated catalogue.

***

## Phase 4 — Partner pilot (\~3 months)

**Goal:** 3–5 trusted external partners shipping mini-apps to a beta channel of users.

### Tasks

* Build the partner dashboard (basic version: submission, status, telemetry).
* Build `based-cli` and the standalone simulator.
* Stand up the docs site (auto-generated reference + 5–10 hand-written guides).
* Stand up the platform CI for partner submissions.
* Set up the kill list endpoint and rotation procedures.
* Onboard 3–5 partners; weekly check-ins.

### Exit criteria

* 3+ partners have shipped to beta.
* Real partner mini-apps are running in production for opted-in users.
* Bridge has stabilized: < 5 breaking change proposals/month.
* We have a documented partner playbook from the support burden we've seen.

### Risks (these are the big ones)

| Risk                                                          | Mitigation                                                                                               |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Partners hit catalog gaps faster than we can add widgets.** | Triaged backlog, fast-path additions, willing to add an "experimental" namespace for non-stable widgets. |
| **The bridge surface mutates more than expected.**            | Compat shim discipline; semver pain is now, not after GA.                                                |
| **App Store review of host updates becomes a chokepoint.**    | Cache compat shims aggressively; minimize host-version dependencies in mini-apps.                        |
| **A partner ships abuse and we discover monitoring gaps.**    | Pre-define the alert thresholds before partner pilot starts. Run a tabletop drill.                       |

***

## Phase 5 — External GA (\~3 months)

**Goal:** open the platform to long-tail third-party developers (with review).

### Tasks

* Self-service partner onboarding (KYC, account, key generation).
* Public docs site with full reference and migration guides.
* Marketplace / discovery UX in the host (probably a small new screen).
* Reviewer tooling: queue management, diff review for permission changes, automated triage.
* Public changelog and breaking-change policy doc.
* A second tier ("verified partner") with relaxed limits, earned via track record.

### Exit criteria

* 10+ live mini-apps from a mix of first/third party.
* Self-service flow works without platform-team intervention for a typical submission.
* Sandbox escape incidents: 0 over the last 90 days.

***

## Cross-cutting workstreams

These run across multiple phases.

### Security review

* Phase 1: threat model finalized (this doc + `08`).
* Phase 2: third-party security audit of the bridge and runtime before any external partner is onboarded.
* Phase 3: ongoing — every PR to `based_mini_app_sdk` or `based_js_runtime` requires platform-team review.
* Phase 4: full audit before public GA.

### Performance budget

* Phase 2: instrument boot, bridge round-trip, render diff times.
* Phase 3: enforce budget per-PR via a perf CI job (best-effort).
* Phase 4: per-mini-app perf telemetry + alerting.

### Documentation

* Each phase ends with the relevant docs in this directory updated from `Draft` → `Reviewed` (and eventually `Approved`).
* Public docs site (phase 4+) is auto-deployed from a `docs-public/` directory; internal docs (this directory) stay in-repo.

***

## Decision points

These are the moments where we explicitly stop and decide whether to continue. The platform team commits to a written go/no-go at each:

| Point          | Question                                                                                 | If no-go, what then                                                                              |
| -------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| End of phase 2 | Did the runtime hit the perf budget? Is the security model holding up under team review? | Re-scope: drop catalog items, defer features, extend phase.                                      |
| Mid-phase 3    | Does the first mini-app feel as good as the native version?                              | Polish more in phase 3 before opening phase 4; don't onboard partners on an unfinished platform. |
| End of phase 4 | Are partners productive? Are they willing to extend beyond beta?                         | Iterate on DX in a smaller, longer phase 4 before considering GA.                                |

***

## What this plan deliberately doesn't include

* A revenue/billing model. Out of scope until phase 5+.
* A native module extension API. Out of scope for v1.
* A websocket bridge (`based.ws.*`). Deferred to v2.
* A WeChat-style "swipe out of mini-app to go back" gesture. Nice-to-have; tracked separately.
* iOS / Android widgets ("home screen extensions" backed by mini-apps). Plausible v3.

Read [`12-open-questions.md`](/docs/integrations/mini-apps-platform/12-open-questions.md) next.