Reliable hot-loading for Super App miniapps: architecture and rollback

Problem: users see old bugs for weeks

Suppose your e-commerce Super App contains a miniapp 'Shopping Cart'. You fix a discount calculation bug, but it takes 2–5 days for the update to pass App Store review. If it's not a critical bug, waiting for the next app release means another 2–4 weeks. As a result, users see the error, conversion drops by 15–20%, and business loses revenue. A hot-loading system for miniapps solves this: you publish a new bundle to a CDN, and within minutes it reaches everyone. But the implementation is simple only in words. We have implemented dozens of such systems — we share the architecture that doesn't crash. Order a hot-loading architecture for your project — we will help avoid typical mistakes.

Hot-loading system architecture

Hot-loading for miniapps is not the same as Hot Module Replacement in Webpack. It is a CDN-based delivery system with version control and rollback capability.

Basic flow:

1. Developer publishes a new version of the miniapp (new bundle.zip on CDN)
2. Platform updates the manifest — a JSON with metadata and URL of the new bundle
3. Super App periodically (or on launch) checks the manifest server
4. If the version has changed — downloads the new bundle in the background
5. On the next miniapp open — loads the new bundle

The devil is in the details of steps 3–5.

Update check strategies: comparison

In practice, we combine: silent push as the main channel + polling on startup as a fallback for devices where the push didn't arrive. Silent push via APNs delivers the update in an average of 5 minutes — 10 times faster than daily scheduled polling. Polling on startup ensures 99.5% delivery within an hour for all devices.

Why atomic update is critical?

You cannot apply the bundle during an active miniapp session. Replacing files while the WebView is running guarantees a crash.

Solution — staged swap:

/miniapps/com.vendor.app/
  current/          <- current active bundle (v2.3.1)
  pending/          <- downloaded but not yet applied (v2.3.2)
  rollback/         <- previous bundle for rollback (v2.3.0)

pending becomes current only at the next cold start of the miniapp. Renaming a directory is an atomic file-system operation. If the host crashes during the swap, pending remains as is, and the attempt repeats on the next launch.

// iOS
let baseURL = FileManager.default.applicationSupportDirectory
let appDir = baseURL.appendingPathComponent("miniapps/com.vendor.app/")
let currentDir = appDir.appendingPathComponent("current")
let pendingDir = appDir.appendingPathComponent("pending")
let rollbackDir = appDir.appendingPathComponent("rollback")

Verification before application

Before applying the new bundle — verification:

// iOS
let expectedHash = manifest.bundleHash  // "sha256:a3f8c2..."
let actualHash = SHA256.hash(data: bundleData).hexString
guard "sha256:\(actualHash)" == expectedHash else {
    throw BundleError.hashMismatch
}

Additionally: digital signature verification of the manifest (platform signs manifest with private key, client verifies with public key). This protects against attacks where the CDN replaces the bundle with a malicious one.

If verification fails — the bundle is deleted, we continue using the current version. Analytics receives a hash mismatch event for monitoring.

How to protect against crash loops?

The new bundle may contain a JS error that causes a crash loop. Automatic rollback is needed.

Mechanism: the container counts consecutive crashes when loading the miniapp. If 3 crashes in a row on startup — roll back to the rollback/ directory (the previous known working version). Analytics event, developer notification via portal.

A crash is defined as: WKWebView navigation finished with an error, or JS threw an uncaught exception within 2 seconds of loading, or the bridge did not respond to the init-handshake within 5 seconds.

On the platform side — ability for emergency rollback: change currentVersion in the manifest to the previous one. All clients that check the manifest will download the 'old' bundle. This takes minutes, not hours.

Differential updates: saving 10–30 times bandwidth

For large bundles (>1 MB) — differential patches instead of full replacements. The bsdiff algorithm (Colin Percival, 2003): for updating v2.3.1 → v2.3.2, a patch file is generated that is 10–30 times smaller than the full bundle. The client downloads the patch, applies it to the current bundle, and gets the new one. Users with slow internet save up to 95% bandwidth. For a project with 500k users, bandwidth savings from differential patches amount to up to 90%.

Requires storing the binary bundle on the client (not only extracted files) for patch application. Complicates implementation, but is critical for users with slow internet.

Typical problems and solutions

What is included in a turnkey hot-loading implementation

• Architecture design: delivery strategy selection, manifest API schema
• Client-side loader implementation (iOS/Android) with verification and rollback
• CDN aggregator and publication API development
• CI/CD integration: automatic bundle publication on merge to main
• API documentation and configuration schema
• Load testing (simulating 1000+ concurrent requests)
• Post-release support: monitoring, alerts, hotfix via emergency rollback

Timelines for implementing a hot-loading system from scratch (manifest API + CDN + client-side loader with verification + rollback): 6 to 12 weeks. With differential patches — add another 3–4 weeks. Get a consultation — we will assess your project and propose the optimal architecture.

Our experience: 10+ years in mobile development

We have implemented hot-loading in the Super App of four major clients with an audience of over 1 million users each. Not a single incident of data loss or miniapp unavailability after more than 500 releases. We use the same approaches described above. Order development — we guarantee reliability and speed.

Mobile App Architecture

The app is built in a single ViewController with 2000 lines. Network calls, business logic, UI updates—all in one place. Adding a new feature without regression is difficult, writing a test is impossible. This isn’t “bad code”—it’s a lack of architecture. And it’s more common than you might expect, even in production apps with millions of users.

We design architecture turnkey: from pattern selection to complete project structure with tests and documentation. In 7–10 days you get clean, modular code ready for scaling.

Architecture patterns in mobile solve one problem: separate UI from logic so each part is testable and replaceable.

MVVM: Basic Pattern

Model-View-ViewModel is the standard for iOS (SwiftUI + Combine/async, UIKit + Combine) and Android (Jetpack ViewModel + StateFlow + Compose). The ViewModel holds UI state and business logic. The View only displays state and forwards user intentions to the ViewModel. The Model represents data and its source.

Key rule: ViewModel knows nothing about UIKit or Android View classes. No UIKit imports, no Context dependencies (except Application context through Hilt). This ensures testability: ViewModel is tested as pure Kotlin/Swift code without Android Instrumented Test.

MVVM covers 70% of needs. The remaining 30% require strict feature isolation, team scaling, or complex state management flows.

Clean Architecture: When MVVM Isn’t Enough

Adds layers on top of MVVM:

• Domain layer — business logic, platform-independent. A UseCase (or Interactor) contains a single business rule: GetUserOrdersUseCase, PlaceOrderUseCase. Depends only on interfaces (protocol/interface), not concrete implementations.
• Data layer — repository implementations. OrderRepositoryImpl implements OrderRepository from domain. Knows about Retrofit, Room, UserDefaults. The ViewModel doesn’t know where data comes from—network or cache.
• Presentation layer — ViewModel + View. Knows about Domain, not Data.

Dependency rule: dependencies point inward only. Domain depends on nothing. Data and Presentation depend on Domain.

Presentation → Domain ← Data

This allows swapping implementations: tests use an in-memory repository instead of network, the interface remains the same.

Practical caveat: Clean Architecture adds files and layers. For small apps, this is overhead. It’s justified starting from ~15 features and teams of 3+ developers.

BLoC for Flutter: Predictable State Flow

BLoC (Business Logic Component) is the standard pattern in the Flutter community. The flutter_bloc library implements it with two types: Bloc (Event → State) and Cubit (State without Events, only methods).

Bloc processes Event and emits a new State via on<EventType> handlers. State is immutable—a new object for each change. BlocBuilder re-renders only the part of the tree where state changed.

// Event
abstract class CartEvent {}
class AddItemToCart extends CartEvent {
  final String productId;
  AddItemToCart(this.productId);
}

// State
abstract class CartState {}
class CartLoaded extends CartState {
  final List<CartItem> items;
  CartLoaded(this.items);
}

// Bloc
class CartBloc extends Bloc<CartEvent, CartState> {
  CartBloc(this._cartRepository) : super(CartLoaded([])) {
    on<AddItemToCart>(_onAddItem);
  }

  Future<void> _onAddItem(AddItemToCart event, Emitter<CartState> emit) async {
    final current = state as CartLoaded;
    final updated = await _cartRepository.addItem(event.productId);
    emit(CartLoaded(updated));
  }
}

The advantage of BLoC is testability. blocTest from the bloc_test package allows you to verify: given a certain Event and initial State, the BLoC should emit a certain State. No UI, no mocks for the Flutter framework.

VIPER: For Large iOS Projects

VIPER (View, Interactor, Presenter, Entity, Router) is the strictest separation of responsibilities for iOS. Each component has a protocol and concrete implementation.

• View — UI only, delegates everything to Presenter
• Interactor — business logic, network and data operations
• Presenter — mediator between View and Interactor, formats data for View
• Entity — data models (pure structures)
• Router — navigation between modules

Each module (screen or feature) is a separate VIPER module. This eliminates coupling between features and allows large teams to work in parallel without conflicts.

The cost: many files, many protocols. Boilerplate is generated via Sourcery or custom Xcode templates. VIPER is justified for apps with 10+ developers and 50+ screens.

TCA (The Composable Architecture)

TCA by Point-Free is a more modern alternative to VIPER for iOS/macOS. Core concepts: State (immutable feature state), Action (all possible events), Reducer (State + Action → new State + Effect), Store (holds State, processes Actions).

Scope allows composable building of large features from small ones: a parent Reducer delegates part of State to a child. Each feature is tested in isolation via TestStore with precise control over Effects.

TCA has a steep learning curve but provides predictability that is hard to achieve otherwise: every state change is an explicit Action with a specific source.

Which Pattern to Choose for Your Project?

We’ll evaluate your project in 1 day—choose an architecture considering team size, platform, and growth plans.

There is no universal answer. Architecture is chosen based on team size, testability requirements, and app support horizon.

What Components Are Included in Our Architecture Work?

• Audit of current architecture (if the app already exists)—identify bottlenecks and regression areas.
• Design of modular structure with clear layer boundaries and dependency rules.
• Creation of project scaffold with DI setup, folder organization, and linter configuration.
• Writing unit tests for domain layer and ViewModel—minimum 80% coverage of key use cases.
• Preparation of documentation—architecture diagrams, README with code modification rules, onboarding guide for new developers.
• Delivery of a working repository with CI pipeline (GitHub Actions / Bitrise) configured to run tests and static analysis.

All this is included in the design cost. Additionally, support during implementation: team consultations, code review of first pull requests.

How Does Lack of Architecture Affect Development Speed?

Typical scenario after 18 months without architecture: 40% of development time goes to debugging regressions. A new developer spends a week understanding the code before making their first PR. Tests aren’t written “because it’s hard to mock.” Adding a new feature requires understanding half the codebase.

Choosing architecture at the start is an investment that pays off in 3–6 months. According to our data, a properly designed architecture with MVVM + Clean gives 3x fewer regressions compared to a monolithic ViewController. And the cost of implementation is recouped in 2–3 sprints.

According to Apple’s recommendations, separation of responsibilities is a key factor in code stability.

Why Trust Our Team with Architecture?

An incorrect pattern choice at the start leads to rewriting half the code a year later. We’ve seen dozens of projects where trying to save on architecture resulted in months of refactoring. With over 10 years of commercial development experience and work on apps from 1 to 50 developers, we help avoid common mistakes:

• Overengineering for a simple MVP (we assign MVVM, not VIPER).
• Lack of dependency injection—we integrate Hilt/Koin/Dagger from the start.
• Ignoring testability—we establish protocols/interfaces from the first commit.

We’ve architected over 200 mobile applications for startups and enterprises, with guaranteed 80%+ test coverage and CI/CD pipelines. Our team holds certifications in iOS and Android development, and we follow the App Store Review Guidelines (Section 4.2/5.1) to ensure smooth store approvals.

Start with a free architecture audit — send us your project description and we’ll deliver a tailored architecture plan within 24 hours. Reach out via Telegram or email to get started.