apps/flutter_appThin Flutter runner and bootstrap.
Featured engineering project · 2026
Personal Engineering / Platform Architecture Project
Super App Platform
Architected a Flutter super-app platform for sandboxed H5 mini-apps, combining a capability-based native bridge, secure WebView boundaries, signed manifests, generated SDK/contracts and a NestJS backend.
Flutter · Dart · Melos · WebView · OpenAPI · NestJS · Firebase · Fastlane · Docker
Case study index
Why a Super App Platform?
A mini-app model can increase feature delivery speed, but only if the host remains the policy enforcement point. This project explores how independently delivered H5 experiences can reuse identity, payments, device services and navigation without inheriting unrestricted native access.
The host owns policy. Mini-apps request narrowly scoped capabilities.
Platform Architecture
The platform separates the thin runner, product host, runtime policy models, Flutter WebView hosting, SDKs, generated clients and backend services. Each boundary has a clear responsibility and contract.
EXPERIENCE
Flutter HostH5 Mini-app Store
↓PLATFORM
Mini-app RuntimeSDK / OpenAPI Contracts
↓SERVICES
NestJS BackendFirebase / Fastlane / Docker
MOBILE ARCHITECTURE
Clean Architecture · BLoC · go_router · get_it / injectable · modular feature boundaries · Android/iOS native glue
SHARED INFRASTRUCTURE
Networking · local storage · secure storage · domain · analytics
Repository boundaries
packages/superapp_hostMain application code and product features.
packages/miniapp_runtimeDescriptors, sessions, policies, registry, lifecycle and authorization scopes.
packages/miniapp_flutterFlutter WebView hosting layer.
packages/superapp_sdkDart-facing bridge SDK.
packages/superapp_api_clientGenerated OpenAPI client.
backend/NestJS platform services and domain modules.
mini_apps_store/ + contracts/H5 hosting, JavaScript SDK, registry and contract workflow.
Mini-app Runtime
The runtime models descriptors, sessions, policies, capability registration, lifecycle, authorization scopes, bundle versions, cache and revocation. Launch is a gated decision, not a direct URL open.
Host product scope
AuthenticationSplash / bootstrapMini-app catalogMini-app runtimePayment integrationDeep linksQR launchPermissionsConsentBundle / cache / versionStorage / share / deviceRevocation
Trust Boundary
H5 code is treated as untrusted input. It can request capabilities, but it cannot directly reach payment credentials, platform secrets or unrestricted device APIs. The Flutter host authenticates the session, evaluates policy and routes approved work to native services or the backend.
UNTRUSTEDH5 / WebView
POLICY ENFORCEMENTFlutter Host
PRIVILEGEDNative / Backend
Capability-based Bridge
Every bridge message crosses an explicit validation and authorization pipeline before a host capability is invoked.
- 01H5 Mini App↓
- 02JavaScript SDK↓
- 03WebView Bridge↓
- 04Origin · Schema · Rate Limit · Codec · Audit↓
- 05Session-aware Capability Authorization↓
- 06Flutter Host Services↓
- 07Native Platform / Backend↓
- 08External Services
CAPABILITIESUser · Payment · Device · Storage · Share · Navigation
Security Model
Security controls are placed at the boundaries where untrusted H5 content meets privileged mobile and backend capabilities.
WebView isolation
Restrict bridge origins and enforce main-frame/origin boundaries before dispatch.
Signed manifests
Verify Ed25519/JWKS signatures; the mobile host never holds the signing private key.
Secure storage
Sensitive authentication material uses platform Keychain/Keystore-backed storage.
Payment mediation
WebView → native host → backend → provider. Provider credentials stay outside H5; server-to-server calls use a service-token boundary.
Fail-closed launches
superapp://miniapp/<id> deep links and QR launches pass through registry, policy and version gates.
Revocation
Client kill-switch support complements backend revocation mechanisms.
Contract / SDK Strategy
OpenAPI is the shared source of truth for generated Dart and TypeScript clients. Contract CI checks breaking changes so the mobile host, mini-app developers and backend evolve against explicit interfaces instead of informal API assumptions.
OpenAPI→Dart Client+TypeScript SDK→Contract CI
Backend & Artifact Supply Chain
The NestJS platform covers auth, OAuth, identity, organizations, mini-apps, payments, analytics, revocation and users. The artifact path adds digest verification, quarantine, fail-closed scanning, an append-only release ledger, rollback and ZIP/bundle defenses.
Artifact digestQuarantineFail-closed scannerAppend-only ledgerRollbackZIP / bundle defensesGovernance review
Release & Quality Gates
The latest Gate 3 integration checkpoint passes 1,166 / 1,166 tests across Flutter/Dart and backend coverage, with five workflows green. Integration maturity is verified; production readiness remains gated behind the remaining reviews.
Current Status
The platform remains deliberately gated before production. The remaining items are visible release conditions rather than hidden uncertainty.
Independent security review is not fully closed.
Baseline reconciliation has an external pending dependency.
Production flags remain disabled.
Final production GO has not been given.
Engineering Trade-offs
The architecture makes its costs visible instead of presenting every control as free.
Delivery speed vs. authority
H5 enables independent delivery; capability mediation deliberately limits what a mini-app can do.
Explicit contracts vs. workflow cost
Generated clients and breaking-change checks add process, but reduce drift between host, mini-app and backend.
Fail-closed vs. availability
A blocked launch is preferable to bypassing an unverifiable manifest, policy or artifact state.
Native mediation vs. simplicity
The bridge adds lifecycle and observability work, but keeps privileged actions inside the mobile trust boundary.