Skip to main content

Frequently Asked Questions (FAQ)

Find comprehensive answers to the technical questions most frequently raised by software architects, CISOs, and mobile engineering teams operating TkushPatch.

1. Architecture and General Principles​

Q1. What is TkushPatch exactly?​

TkushPatch is a sovereign, self-hostable Over-The-Air (OTA) Code Push platform for Flutter mobile applications. It enables engineering teams to deploy hotfixes and business logic updates directly to end-user devices in seconds, bypassing external app store review pipelines entirely.

Q2. How does TkushPatch differ from Shorebird Cloud?​

TkushPatch provides absolute data sovereignty: the entire backend server (ota-server), management console (ota-web-console), cryptographic signing engine signing adapter, and central database run on your private infrastructure. Zero telemetry or compiled code leaves your sovereign perimeter. Furthermore, TkushPatch natively embeds banking Four-Eyes governance, country geo-targeting, and hardened 2FA OTP controls.

Q3. What programming languages and frameworks power TkushPatch?​

  • Data Plane & Updater Client: Standalone native engine written in Rust (updater/library) for deterministic performance and memory safety.
  • Backend API (Control Plane): TkushPatch Server 3 (Java 21) following hexagonal architecture patterns, backed by database and cryptographic signing engine.
  • Web Console: Next.js 15 (React 19, TypeScript, Tailwind CSS).
  • Developer CLI: Native tooling written in Dart (tk-ota-push).
  • Client SDK: Native Flutter package (tk_ota_push).

Q4. Does TkushPatch support all Flutter releases?​

TkushPatch supports stable Flutter versions starting from Flutter 3.10.x through modern 3.x releases on both Android and iOS targets.

Q5. Will the mobile application operate normally if the TkushPatch server is offline?​

Yes, seamlessly. If an end-user device is offline or the server is momentarily unreachable, the mobile SDK silently skips update checks and continues executing the latest verified cached version or the pristine baseline Store binary.

2. Binary Differentials and Algorithmic Mechanics​

Q6. How does TkushPatch generate patches that are only a few dozen kilobytes in size?​

TkushPatch never transmits full recompiled binary shared libraries (application binary). It executes the binary diff differential algorithm coupled with high-efficiency optimized compression compression. The compiler isolates the exact byte delta between the baseline binary and target binary, generating a micro-differential payload that typically measures between 1% and 3% of the overall binary size.

Q7. What types of source code changes can be delivered via an OTA patch?​

All Dart code, Flutter UI widgets, business logic layers, state management trees, localization string dictionaries, API integration calls, and bundled static assets (images, fonts).

Q8. What modifications CANNOT be deployed via an OTA patch?​

Modifications altering underlying native platform code:

  • C++ / Java / Kotlin code (files under android/ or third-party plugins introducing native code).
  • Objective-C / Swift code (files under ios/).
  • System-level manifest permission changes (AndroidManifest.xml or Info.plist). Any native modification mandates building a new baseline release for Store submission.

Q9. What happens if a developer attempts to patch native platform code?​

The CLI compiler and web approval gates inspect native bridge hashes automatically. If a native alteration is detected, the patch is blocked by the safety gate patch.native_bridge_ok == false and rejected before signing.

3. Security, Cryptography, and the Four-Eyes Principle​

Q10. How is patch authenticity and origin guaranteed?​

Every patch is asymmetrically signed with an isolated digital signature/4096 private key held inside cryptographic signing engine. During initial baseline Store compilation, the matching public key is permanently embedded into the client binary. The native Rust updater verifies the digital signature signature before mapping code into memory.

Q11. What is the Four-Eyes (Maker-Checker) approval principle?​

It is a banking regulatory requirement barring any single individual from shipping code unilaterally:

  • The mobile developer (Maker) compiles and uploads the patch, placing it in STAGED quarantine.
  • The security officer (Checker) audits the diff on /approvals and authorizes cryptographic signing engine to sign it. Self-approval is blocked whenever the organization contains more than one team member.

Q12. How does Solo Developer Mode operate?​

When an organization account has only one registered member (totalMembers == 1), self-approval is permitted by explicit exception to prevent operational deadlocks. The action is marked in the audit database under PATCH_APPROVED_SOLO_OVERRIDE. Once a second collaborator accepts an invite, strict Four-Eyes gates engage automatically.

Q13. Are 2FA OTP verification codes stored in cleartext?​

No. Raw 6-digit challenge codes are generated via SecureRandom CSPRNG, salted with an organizational secret, and hashed using SHA-256. Only the resulting hash is committed to the database.

Q14. What occurs if an OTA patch payload gets corrupted during transit?​

The native Rust updater recomputes the SHA-256 digest of the downloaded payload. If the hash fails to match the expected signature or digest, the file is immediately purged from device flash and the application falls back safely to its previous version.

4. App Store Compliance (Google Play and Apple App Store)​

Q15. Is using Code Push permitted on Google Play?​

Yes. Google Play Developer Program Policies explicitly permit dynamic updates for interpreted or virtual-machine-executed code (such as the Flutter/Dart runtime), provided the modifications do not alter the core functionality or primary purpose declared on the Store listing.

Q16. How does this comply with Apple App Store Guidelines (Section 3.3.2)?​

The Apple Developer Program License Agreement (Section 3.3.2) explicitly permits code push for interpreted code and scripts running within cross-platform frameworks, provided the code does not violate platform security boundaries or introduce prohibited capabilities.

Q17. How can teams ensure OTA patches do not interfere with Store App Review?​

TkushPatch features the Store Review Shield (IN_STORE_REVIEW). During testing and validation by Apple or Google App Review teams, the sovereign server suspends OTA patch delivery for the pending version, guaranteeing reviewers evaluate the exact submitted binary without OTA drift.

Q18. Why are patch numbers decoupled from Store release versions?​

The Store release version (e.g., 2.4.1+45) identifies the compiled native container audited by marketplace reviewers. OTA patches (Patch #1, Patch #2) represent incremental software updates applied atop this baseline without incrementing the marketplace build sequence.

5. Deployment Tracks, Canary Rollouts, and Update Policies​

Q19. What is a Canary Rollout?​

Canary rollout is a progressive delivery strategy where updates are served to a small segment of the active fleet (e.g., 5%, then 25%, 50%, and 100%). This allows operations teams to measure real-world stability before broad rollout.

Q20. How does Country Geo-Targeting operate?​

The web console allows operators to bound patch availability to specific ISO country codes (e.g. Cameroon CM, Ivory Coast CI, Senegal SN). The server matches the client's public IP geolocation or carrier SIM code to approve or restrict delivery.

Q21. What is the difference between "Wi-Fi Only" and "Forced Update" policies?​

  • Wi-Fi Only: The SDK delays differential downloads until the handset connects to an unmetered Wi-Fi connection, conserving mobile data plans.
  • Forced Update: For critical security hotfixes, the SDK renders a full-screen blocking overlay preventing application usage until the patch has downloaded and rebooted.

Q22. What is Zero-Recompile Inter-Channel Promotion?​

When a patch is certified on the staging channel, operators can promote it to stable with a single click. The backend reuses the exact same .vmcode binary artifact bit-for-bit, guaranteeing the code deployed to customers is identical to what QA validated.

6. Day-2 Operations, Resilience, and Diagnostics​

Q23. What is the Emergency Kill-Switch?​

On the /rollout dashboard, the Kill-Switch allows SREs to revoke an active production patch with 1 click. On their subsequent background check, active mobile clients receive an instruction to purge the patch and instantly fall back to clean Store binaries.

Q24. How does the mobile runtime recover from crash loops caused by bad patches?​

TkushPatch embeds an automated 2-Crash Rollback Guard in its native Rust runtime. If an application encounters fatal crashes twice consecutively upon launch with an active patch, the updater isolates the patch, purges it from cache, and boots cleanly from native Store code.

Q25. How do teams deobfuscate production crash stack traces?​

During every patch compilation, the CLI archives Dart debug mappings in a .symbols file. On the /symbols page, engineers can paste an obfuscated trace (#00 abs 0000007...) to translate hexadecimal memory offsets into precise Dart filenames and line numbers.

Q26. How long are archived patch differentials retained on disk?​

Audit metadata and cryptographic signatures remain indefinitely preserved for compliance purposes. Inactive .vmcode differential binaries older than 90 days can be reclaimed with a single click using the Day-2 Maintenance Purge on /health.