apps/flutter_appFlutter runner và bootstrap mỏng.
Dự án kỹ thuật tiêu biểu · 2026
Dự án kỹ thuật cá nhân / Kiến trúc nền tảng
Super App Platform
Thiết kế nền tảng Super App Flutter chạy các mini-app H5 trong môi trường WebView được kiểm soát, với capability-based bridge, security boundary, signed manifest, SDK/contract sinh tự động và backend NestJS.
Flutter · Dart · Melos · WebView · OpenAPI · NestJS · Firebase · Fastlane · Docker
Mục lục case study
Vì sao xây dựng Super App Platform?
Mô hình mini-app có thể tăng tốc delivery, nhưng chỉ khi host vẫn là điểm thực thi policy. Dự án này giải quyết cách các trải nghiệm H5 được phát triển độc lập có thể dùng chung identity, payment, device service và navigation mà không nhận quyền native không giới hạn.
Host làm chủ policy. Mini-app chỉ yêu cầu capability với scope hẹp.
Kiến trúc nền tảng
Nền tảng tách thin runner, product host, runtime policy model, lớp Flutter WebView, SDK, generated client và backend service. Mỗi boundary có trách nhiệm và contract rõ ràng.
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
Boundary trong repository
packages/superapp_hostApplication code và product feature chính.
packages/miniapp_runtimeDescriptor, session, policy, registry, lifecycle và authorization scope.
packages/miniapp_flutterLớp Flutter WebView hosting.
packages/superapp_sdkBridge SDK phía Dart.
packages/superapp_api_clientOpenAPI client được sinh tự động.
backend/Platform service và domain module NestJS.
mini_apps_store/ + contracts/H5 hosting, JavaScript SDK, registry và contract workflow.
Mini-app Runtime
Runtime mô hình hóa descriptor, session, policy, capability registry, lifecycle, authorization scope, bundle version, cache và revocation. Launch là một quyết định qua gate, không phải thao tác mở URL trực tiếp.
Phạm vi product của host
AuthenticationSplash / bootstrapMini-app catalogMini-app runtimePayment integrationDeep linksQR launchPermissionsConsentBundle / cache / versionStorage / share / deviceRevocation
Trust Boundary
H5 được xem là nguồn input không tin cậy. Mini-app có thể yêu cầu capability nhưng không thể trực tiếp chạm vào payment credential, platform secret hoặc device API không giới hạn. Flutter host xác thực session, đánh giá policy và chỉ chuyển tác vụ hợp lệ tới native service hoặc backend.
KHÔNG TIN CẬYH5 / WebView
POLICY ENFORCEMENTFlutter Host
ĐƯỢC BẢO VỆNative / Backend
Capability-based Bridge
Mọi bridge message đều đi qua pipeline validation và authorization tường minh trước khi một host capability được thực thi.
- 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
Mô hình bảo mật
Security control được đặt tại các boundary nơi nội dung H5 không tin cậy gặp capability có đặc quyền của mobile và backend.
WebView isolation
Giới hạn origin của bridge và thực thi main-frame/origin boundary trước dispatch.
Signed manifest
Xác minh chữ ký Ed25519/JWKS; mobile host không giữ signing private key.
Secure storage
Authentication material nhạy cảm dùng storage dựa trên Keychain/Keystore.
Payment mediation
WebView → native host → backend → provider. Credential nằm ngoài H5; call server-to-server dùng service-token boundary.
Launch fail-closed
Deep link superapp://miniapp/<id> và QR launch phải qua registry, policy và version gate.
Revocation
Client kill-switch bổ sung cho cơ chế revocation phía backend.
Chiến lược Contract / SDK
OpenAPI là source of truth dùng chung để sinh Dart và TypeScript client. Contract CI kiểm tra breaking change để mobile host, mini-app developer và backend phát triển trên interface tường minh thay vì giả định API không chính thức.
OpenAPI→Dart Client+TypeScript SDK→Contract CI
Backend & chuỗi cung ứng artifact
Nền tảng NestJS gồm auth, OAuth, identity, organization, mini-app, payment, analytics, revocation và user. Artifact pipeline bổ sung digest verification, quarantine, fail-closed scanning, release ledger append-only, rollback và phòng vệ ZIP/bundle.
Artifact digestQuarantineFail-closed scannerAppend-only ledgerRollbackZIP / bundle defensesGovernance review
Release & Quality Gates
Checkpoint tích hợp Gate 3 gần nhất đạt 1.166 / 1.166 test trên Flutter/Dart và backend, với năm workflow xanh. Độ chín tích hợp đã được kiểm chứng; production readiness vẫn qua các review còn lại.
Trạng thái hiện tại
Nền tảng chủ động giữ gate trước production. Các hạng mục còn lại được thể hiện như điều kiện release rõ ràng, không phải rủi ro bị che giấu.
Independent security review chưa đóng hoàn toàn.
Baseline reconciliation còn dependency bên ngoài đang chờ.
Production flags tiếp tục bị vô hiệu hóa.
Chưa có quyết định GO production cuối cùng.
Đánh đổi kỹ thuật
Kiến trúc thể hiện rõ chi phí thay vì coi mọi control là miễn phí.
Tốc độ delivery vs. quyền hạn
H5 cho phép delivery độc lập; capability mediation chủ động giới hạn quyền của mini-app.
Contract tường minh vs. chi phí workflow
Generated client và breaking-change check tăng quy trình nhưng giảm drift giữa host, mini-app và backend.
Fail-closed vs. availability
Chặn launch tốt hơn bỏ qua manifest, policy hoặc artifact state không thể xác minh.
Native mediation vs. độ đơn giản
Bridge tăng công việc lifecycle và observability nhưng giữ privileged action trong trust boundary của mobile.