super-app

How it is built

Architecture overview

A super-app is one installed app that acts as a platform: inside it live chat, a wallet, search and a store of mini-programs, small apps written by third parties, loaded in seconds without an app-store install, and run inside a sandbox the host controls. WeChat and Alipay are the reference examples; Grab, Gojek and Paytm built the same shape around rides, delivery and payments. The host owns three things that third parties cannot: the identity of the user, the payment rail and the distribution channel. The one idea that makes the design work is the contract between host and mini-program: the mini-program runs in a restricted runtime and may only reach the phone, the network, the user's identity and the wallet through host APIs that ask permission, log the call and can be revoked remotely. Everything else (the chat service, the search, the package delivery, the rollout system) exists to make that contract fast and safe at the scale of hundreds of millions of users and many thousands of developers.

Parts:

• Mini-program runtime — loads a package, runs its logic and view in a sandbox, exposes host APIs — Process sandboxing, javascript-event-loop (no page yet), Cryptographic hashes (SHA-2, BLAKE3), Digital signatures (Ed25519)
• Distribution and rollout — packages to the device, versions, gradual release, experiments — CDN and edge, Deterministic bucketing, Incremental sync cursors, Consistent hashing
• Identity and authorisation — one user, a different identifier per mini-program, scopes the user grants — OAuth 2 and OpenID Connect, Distributed ID generation
• Messaging — chat, groups, presence, notifications — WebSockets, Pub/sub fan-out, Presence tracking, Message sequence numbers, Mobile push delivery
• Search — find people, content, mini-programs and services in one box — Inverted index, BM25 ranking, Learning to rank, Aho-Corasick multi-pattern matching
• Wallet and payments — balance, pay-in-mini-program, refunds — Double-entry ledger, Payment state machine, Idempotency keys
• Platform operations — storage, failover, deploys, service-to-service security, testing — Primary-backup replication, Point-in-time recovery, Process supervision, Graceful draining, Mutual TLS, Deterministic simulation testing, Coverage-guided fuzzing, hdr-histogram (no page yet)

 developer ──upload package──► review + scan ──► sign (Ed25519) ──► package store ──► CDN / edge
                                    │ hash                                              │
                                    ▼                                                   ▼
 user device ───────────────────────────────────────────────────────────────── host app (native)
   ┌─────────────────────────────────────────────────────────────────────┐
   │ mini-program sandbox            host bridge (permissions, logging)  │
   │  logic (JS, event loop) ◄─────► view (render) ◄── host APIs: login, pay, location, scan
   └────────────────────────────┬────────────────────────────────────────┘
                                │ HTTPS / WebSocket
        ┌───────────────┬───────┴────────┬───────────────┬──────────────┐
      identity        messaging        search         wallet          rollout (buckets)
     (OAuth-like     (fan-out,       (index, rank,   (ledger, payment   config + kill switch
      per-app ids)    seq numbers)    moderation)     state machine)

How the parts fit together

Mini-program runtime

A mini-program is a package: pages, styles, scripts and a manifest. The WeChat framework documentation splits it into two parts, the App Service (the logic layer, JavaScript) and the View layer, and describes a data-binding system between them: the logic layer changes data with setData and the view layer updates itself (source: WeChat Mini Program documentation, framework). The two layers run apart, the logic in a sandboxed JavaScript engine and the view in a renderer, and every call to the phone or the network goes through the host's bridge. This separation is the sandbox in practice (Process sandboxing): the logic code has no DOM, no direct file or socket access, and no way to touch the host's memory. The logic layer is single-threaded and event-driven (javascript-event-loop, no page yet), so a long computation freezes its own page but not the host; the framework offers a separate worker for heavy work.

The host decides the lifecycle. WeChat's documentation describes cold start, running in the background, and destruction by the system at any time, and gives a mini-program an exit-state hook: the page can save a small JSON state with an expiry (default one day) that is restored on the next cold start, if the host manages to call it at all (source: WeChat Mini Program documentation, operating mechanism). Design consequence: a mini-program must be restartable from storage and server state, and the host must keep memory in check by killing backgrounded programs.

Why a standard exists but has little weight: the W3C MiniApps Working Group published a packaging specification, defining a single-file container with a manifest, page templates, stylesheets and scripts, but it now carries the status "Discontinued Draft" (source: W3C, MiniApp Packaging, dated 11 August 2026). Each super-app still has its own package format and API set, so cross-platform frameworks such as Taro and uni-app compile one source to several platforms' mini-program formats instead.

Platform rules apply from outside, too. Apple's App Store guidelines allow HTML5 and JavaScript mini apps inside an app, make the host app responsible for their compliance, and forbid exposing native platform APIs to them without Apple's permission (source: Apple, App Store Review Guidelines, 4.7). The host bridge is therefore also a policy boundary, not only a technical one.

Distribution and rollout

A package is fetched on first open and cached. Integrity and origin matter more than in a web page, because the package runs inside a trusted app with access to payments. The build pipeline computes a content hash of the package and signs it with a platform key (Digital signatures (Ed25519)); the host verifies the signature before it runs the code, so a compromised CDN or a man in the middle can serve bytes but not a valid program. (The sources checked here do not document WeChat's or Alipay's signing scheme; this is the standard design the blocks describe.) Delivery goes through a CDN and edge with the package addressed by hash, so versions are immutable and cacheable. WeChat's documentation also lists sub-package loading and pre-download of sub-packages, which keeps the first download small and fetches the rest when needed (source: WeChat Mini Program documentation, index of framework topics).

Rollout is staged and reversible. Deterministic bucketing hashes a user or device identifier with the experiment name into a bucket, so the same user always sees the same version, and a release can go to 1 %, 10 %, 100 % by moving a threshold. A kill switch on a mini-program version (the host refuses to run a version ID) is the emergency lever; it is delivered through the same config channel. Which users see which mini-programs and which config version they have is synchronised with Incremental sync cursors: the client asks "changes since cursor N" and never refetches the whole list. Consistent hashing spreads sessions, mini-program state and cache across servers so that adding a node moves only a fraction of the keys.

Identity and authorisation

The user logs in once to the host. A mini-program should not learn who the user is just because the user opened it, so the host issues a different identifier per mini-program and an authorisation step for anything more. WeChat's documentation lists a login flow, a UnionID mechanism (an identifier shared across a developer's apps), user authorisation and verified phone-number components (source: WeChat Mini Program documentation, index of open capabilities). Mechanically this is OAuth 2 and OpenID Connect in a closed ecosystem: the mini-program asks the host for a short-lived code, sends it to its own server, the server exchanges it with the host's backend for the user's per-app identifier and a session key, and any sensitive scope (phone number, location, payment) needs an explicit consent shown by the host, recorded and revocable. Identifiers are minted by Distributed ID generation: time-ordered, unique across many generators without a central counter, and not guessable.

Messaging

Chat is the entry point and the reason people keep the app open. Clients keep a WebSocket to a gateway; messages go to a conversation, and each conversation fans out to its members through Pub/sub fan-out: small groups write the message to every member's inbox, huge groups store once and let members pull. Order and gaps are handled with Message sequence numbers per conversation: the client sees 41, 42, 44 and asks for 43; reconnecting clients say "I have up to 44". Presence tracking shows who is online and typing, with a lease that expires when a heartbeat stops. When the app is not running, Mobile push delivery wakes the phone through the platform's push service; the push is a hint, and the message itself is synced when the app opens.

Search

One search box covers contacts, chat history, public content, mini-programs and services. Documents go into an Inverted index per corpus; first-stage retrieval ranks by BM25 ranking; a Learning to rank model reorders the top candidates using features such as freshness, popularity, personal affinity and click history. Aho-Corasick matches thousands of patterns in one pass, and the platform uses it where many strings must be found at once: spotting a mini-program or brand name inside a query, and screening content and queries against blocked-term lists. Search is also where the platform's rules show up: delisted mini-programs must vanish from the index within minutes.

Wallet and payments

The wallet is a Double-entry ledger of user balances, merchant balances, fees, and holding accounts for money in transit to and from banks. A payment inside a mini-program is a three-party flow: the mini-program's server creates an order with the host's payment API, the host app shows a native confirmation (the mini-program never sees the PIN), and the wallet debits the user and credits the merchant. The order follows a Payment state machine, and every mutating call carries an Idempotency key because the merchant's server and the host's callbacks both retry. The merchant is told of the result by a signed callback, and must treat the host's query API as the source of truth, not the callback alone.

Platform operations

The wallet and identity stores run on Primary-backup replication with Point-in-time recovery. Process supervision restarts failed services; Graceful draining lets connections and in-flight payments finish before a deploy, and matters in particular for long-lived WebSockets, where a naive restart disconnects millions of clients at once. Service-to-service traffic uses Mutual TLS. Deterministic simulation testing covers the stateful services (wallet, message ordering, sync), and Coverage-guided fuzzing covers the parsers that touch untrusted input: package manifests, message formats, query strings. Latency is tracked as full distributions (hdr-histogram, no page yet), per API and per mini-program, because a slow third-party mini-program is blamed on the host.

Data and control flow

Opening a mini-program and paying in it:

1. The user taps a mini-program. The host resolves the identifier and the current version for this user (bucketing, kill-switch check) from its cached config.
2. If the package is not cached, the host downloads it from the edge by hash, verifies the signature, and starts the sandbox. A small main package loads first; further sub-packages load on demand.
3. The mini-program calls the host's login API; the host returns a short-lived code. The mini-program's server exchanges it for the per-app user identifier and a session.
4. The user taps pay. The mini-program's server creates an order at the host with an idempotency key; the host shows the native payment sheet with merchant, amount and currency.
5. The user confirms with a PIN or biometric. The wallet engine reserves the balance, posts the entries, marks the order paid, and queues the callback and the receipt message through an outbox.
6. The mini-program shows success after it queries the order status on its server, which has received the signed callback and verified it against the host's query API.

Sending a chat message:

1. The client sends the message with a client-generated id over its WebSocket.
2. The gateway assigns the next sequence number in the conversation, stores the message, and publishes it.
3. Online members receive it on their sockets; offline members get a push and sync by cursor on opening.

Scaling

1. Package delivery and cold start. First-open latency is mostly download. Lever: small main package plus sub-packages, content-addressed packages on the CDN, preload of likely next mini-programs.
2. Connections. One live socket per active user. Lever: gateways that hold only connections and are stateless otherwise, consistent hashing of sessions, draining on deploy.
3. Fan-out of big groups. Writing to every member's inbox is too expensive for a large group. Lever: store once, fan out on read for large groups, write-fan-out for small ones.
4. Search index size and ranking cost. Lever: shard the inverted index, cheap first stage, a learned ranker on a few hundred candidates only.
5. Payment peaks (a holiday campaign). Lever: partition wallets by user, hot merchant accounts split into sub-accounts, queue non-critical work (receipts, analytics).
6. Developer ecosystem. The number of mini-programs and their versions. Lever: automated review and scanning, rate limits per developer, per-mini-program quotas for storage and API calls.

Failure modes

Real implementations

There is no widely used open-source host runtime to cite from the sources checked; the host side of a super-app is proprietary at every large operator.

Sources

• Tencent, Weixin Mini Program developer documentation: framework, framework introduction, operating mechanism. English pages are machine-translated; the Chinese text prevails.
• Alipay, Mini Program documentation. docs
• W3C MiniApps Working Group, MiniApp Packaging (Discontinued Draft, 11 August 2026). spec
• Apple, App Store Review Guidelines, section 4.7 (mini apps, mini games, plug-ins). guidelines
• Taro. repo; uni-app. repo