Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Cross-platform mobile architecture covering React Native vs Flutter vs Kotlin Multiplatform comparison, shared business logic patterns, native bridge design, platform-specific UI strategies, performance optimization, navigation architecture, state management, testing strategies, and migration paths between frameworks.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
548 lines · 2,146 words
Cross-platform architecture enables building mobile applications for iOS and Android from a shared codebase, balancing development velocity against native performance and UX fidelity. This skill covers the major frameworks (React Native, Flutter, Kotlin Multiplatform), architectural patterns for maximizing code sharing while maintaining native quality, and the engineering decisions that determine project success.
Cross-platform mobile architecture covering React Native vs Flutter vs Kotlin Multiplatform comparison, shared business logic patterns, native bridge design, platform-specific UI strategies, performance optimization, navigation architecture, state management, testing strategies, and migration paths between frameworks.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Cross-Platform Architect skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
Overview
Framework Comparison
Shared Logic Architecture
Native Bridge Design
Performance Optimization
Navigation Architecture
State Management
Testing Strategy
Migration Strategies
Architecture Decision Checklist
When to Use
Output Format
Example
Edge Cases
| Factor | React Native | Flutter | Kotlin Multiplatform |
|---|---|---|---|
| Language | TypeScript/JavaScript | Dart | Kotlin |
| UI Approach | Native components | Custom rendering (Skia) | Native UI per platform |
| Code Sharing | UI + logic | UI + logic | Logic only (UI is native) |
| Typical Sharing % | 80-95% | 90-98% | 50-70% (logic layer) |
| Performance | Good (JSI bridge) | Excellent (compiled) | Excellent (native) |
| Hot Reload | Yes (Fast Refresh) | Yes (sub-second) | Partial (logic only) |
| Bundle Size | ~15-25MB | ~10-20MB | Native baseline |
| Native Integration | Bridge/TurboModules | Platform channels | Direct interop |
| Learning Curve | Low (web devs) | Medium (new lang) | Medium (Kotlin devs) |
| Maturity | 2015, Meta | 2018, Google | 2020, JetBrains |
Choose React Native when:
- Team has strong JavaScript/TypeScript skills
- App is content-heavy (feeds, forms, lists)
- Web app already exists in React
- Fast iteration speed is priority
- Community packages cover your native needs
Choose Flutter when:
- Custom UI/animations are central to the experience
- Pixel-perfect consistency across platforms needed
- Team is willing to learn Dart
- Targeting beyond mobile (web, desktop)
- High performance graphics/animations required
Choose Kotlin Multiplatform when:
- Native UI fidelity is non-negotiable
- Complex business logic needs sharing (not UI)
- Team has strong native development skills
- Existing native apps need logic consolidation
- Platform-specific UX patterns must be followed exactlyPlatform Layer (per-platform)
+-- UI/Views (SwiftUI / Jetpack Compose / React Native JSX / Flutter Widgets)
+-- Platform Services (Camera, GPS, Push, Biometrics)
+-- Dependency Injection (platform-specific implementations)
Shared Layer (cross-platform)
+-- Presentation (ViewModels / BLoC / Hooks)
+-- Domain (Use Cases, Entities, Repository Interfaces)
+-- Data (Repository Implementations, API Client, Local DB)
The key insight: Share everything BELOW the UI layer.
UI should be platform-native for best UX.// Shared business logic layer
// src/domain/usecases/GetUserProfile.ts
export class GetUserProfile {
constructor(private userRepo: UserRepository) {}
async run(userId: string): Promise<UserProfile> {
const user = await this.userRepo.getUser(userId);
const preferences = await this.userRepo.getPreferences(userId);
return {
...user,
displayName: `${user.firstName} ${user.lastName}`,
memberSince: formatDate(user.createdAt),
tier: calculateMembershipTier(user.totalPurchases),
preferences,
};
}
}
// src/domain/repositories/UserRepository.ts
export interface UserRepository {
getUser(userId: string): Promise<User>;
getPreferences(userId: string): Promise<UserPreferences>;
updateProfile(userId: string, updates: Partial<User>): Promise<User>;
}
// src/data/repositories/UserRepositoryImpl.ts
export class UserRepositoryImpl implements UserRepository {
constructor(
private apiClient: ApiClient,
private localDb: LocalDatabase,
private cache: CacheManager,
) {}
async getUser(userId: string): Promise<User> {
// Cache-first strategy
const cached = await this.cache.get<User>(`user:${userId}`);
if (cached && !cached.isExpired) return cached.data;
try {
const user = await this.apiClient.get<User>(`/users/${userId}`);
await this.cache.set(`user:${userId}`, user, { ttl: 300 });
await this.localDb.upsert('users', user);
return user;
} catch (error) {
// Fallback to local DB if offline
const local = await this.localDb.get<User>('users', userId);
if (local) return local;
throw error;
}
}
}// Shared BLoC for user profile
// lib/features/profile/bloc/profile_bloc.dart
class ProfileBloc extends Bloc<ProfileEvent, ProfileState> {
final GetUserProfile getUserProfile;
final UpdateUserProfile updateUserProfile;
ProfileBloc({
required this.getUserProfile,
required this.updateUserProfile,
}) : super(ProfileInitial()) {
on<LoadProfile>(_onLoadProfile);
on<UpdateProfile>(_onUpdateProfile);
}
Future<void> _onLoadProfile(
LoadProfile event,
Emitter<ProfileState> emit,
) async {
emit(ProfileLoading());
try {
final profile = await getUserProfile(event.userId);
emit(ProfileLoaded(profile));
} catch (e) {
emit(ProfileError(e.toString()));
}
}
Future<void> _onUpdateProfile(
UpdateProfile event,
Emitter<ProfileState> emit,
) async {
emit(ProfileUpdating());
try {
final updated = await updateUserProfile(event.userId, event.updates);
emit(ProfileLoaded(updated));
} catch (e) {
emit(ProfileError(e.toString()));
}
}
}// shared/src/commonMain/kotlin/com/myapp/domain/usecase/GetUserProfile.kt
class GetUserProfile(private val userRepository: UserRepository) {
suspend operator fun invoke(userId: String): Result<UserProfile> {
return try {
val user = userRepository.getUser(userId)
val preferences = userRepository.getPreferences(userId)
Result.success(UserProfile(
user = user,
displayName = "${user.firstName} ${user.lastName}",
memberTier = calculateTier(user.totalPurchases),
preferences = preferences,
))
} catch (e: Exception) {
Result.failure(e)
}
}
private fun calculateTier(totalPurchases: Int): MemberTier {
return when {
totalPurchases >= 100 -> MemberTier.PLATINUM
totalPurchases >= 50 -> MemberTier.GOLD
totalPurchases >= 10 -> MemberTier.SILVER
else -> MemberTier.BRONZE
}
}
}
// Platform-specific expect/actual for platform services
// shared/src/commonMain/kotlin/com/myapp/platform/SecureStorage.kt
expect class SecureStorage {
fun store(key: String, value: String)
fun get(key: String): String?
fun delete(key: String)
}
// shared/src/androidMain/kotlin/.../SecureStorage.kt
actual class SecureStorage(context: Context) {
private val prefs = EncryptedSharedPreferences.create(...)
actual fun store(key: String, value: String) = prefs.edit().putString(key, value).apply()
actual fun get(key: String): String? = prefs.getString(key, null)
actual fun delete(key: String) = prefs.edit().remove(key).apply()
}
// shared/src/iosMain/kotlin/.../SecureStorage.kt
actual class SecureStorage {
actual fun store(key: String, value: String) {
KeychainWrapper.standard.set(value, forKey: key)
}
actual fun get(key: String): String? {
return KeychainWrapper.standard.string(forKey: key)
}
actual fun delete(key: String) {
KeychainWrapper.standard.removeObject(forKey: key)
}
}// specs/NativeCameraModule.ts (Codegen spec)
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';
export interface Spec extends TurboModule {
takePhoto(options: {
quality: number;
facing: string;
}): Promise<{
uri: string;
width: number;
height: number;
}>;
requestPermission(): Promise<boolean>;
hasPermission(): boolean;
}
export default TurboModuleRegistry.getEnforcing<Spec>('CameraModule');// Dart side
class NativeBiometrics {
static const _channel = MethodChannel('com.myapp/biometrics');
static Future<bool> authenticate(String reason) async {
try {
final result = await _channel.invokeMethod<bool>('authenticate', {
'reason': reason,
'useFallback': true,
});
return result ?? false;
} on PlatformException catch (e) {
throw BiometricException(e.code, e.message ?? 'Unknown error');
}
}
static Future<BiometricType> availableBiometrics() async {
final String type = await _channel.invokeMethod('getAvailableType');
return BiometricType.values.firstWhere(
(t) => t.name == type,
orElse: () => BiometricType.none,
);
}
}
// Bridge design principles:
// 1. Keep bridge calls async (don't block UI thread)
// 2. Serialize data as simple types (no complex objects across bridge)
// 3. Handle errors on both sides (native exception -> Dart exception)
// 4. Batch bridge calls when possible (reduce crossing overhead)
// 5. Use EventChannel for streams (not repeated method calls)Issue React Native Fix Flutter Fix
------------------------------------------------------------------------
List scrolling jank Use FlashList instead of Use ListView.builder
FlatList; memo components with const widgets
Image loading Use FastImage; resize on Use cached_network_image
native side with resize parameters
Heavy computation Move to native module or Use compute() for
use Worklets (Reanimated) isolate-based processing
Animation stutter Use Reanimated (runs on Keep animations in
UI thread, not JS) composition phase
Startup time Enable Hermes; lazy load Tree shaking; deferred
screens; reduce bundle components; AOT compile
Memory leaks Profile with Flipper; Profile with DevTools;
clean up listeners dispose controllers
Bridge overhead Batch native calls; Minimize platform
(RN specific) use TurboModules (JSI) channel calls; batch data// 1. Memoize expensive components
const ProductCard = React.memo(({ product }: Props) => {
return (
<View>
<FastImage source={{ uri: product.imageUrl }} style={styles.image} />
<Text>{product.name}</Text>
</View>
);
});
// 2. Use FlashList for large lists
import { FlashList } from '@shopify/flash-list';
<FlashList
data={products}
renderItem={({ item }) => <ProductCard product={item} />}
estimatedItemSize={120}
keyExtractor={(item) => item.id}
/> .// 3. Reanimated for 60fps animations
import Animated, {
useSharedValue,
useAnimatedStyle,
withSpring,
} from 'react-native-reanimated';
const translateY = useSharedValue(0);
const animatedStyle = useAnimatedStyle(() => ({
transform: [{ translateY: withSpring(translateY.value) }],
}));Pattern React Native Flutter KMP
----------------------------------------------------------------------
Stack navigation React Navigation Navigator 2.0 / Native per platform
Stack.Navigator GoRouter
Tab navigation Bottom Tabs BottomNavigationBar Native TabBar/
navigator BottomNav
Deep linking Linking config in GoRouter path Native URL handling
React Navigation patterns per platform
Modal presentation Modal stack showModalBottomSheet Native modal
navigator presentation| Approach | React Native | Flutter | When to Use |
|---|---|---|---|
| Local state | useState/useReducer | setState/ValueNotifier | Component-level UI state |
| App state | Redux/Zustand | Riverpod/Provider/BLoC | App-wide shared state |
| Server state | TanStack Query | flutter_query/dio_cache | API data with caching |
| Navigation state | React Navigation state | GoRouter state | URL/screen state |
/\
/ \
/ E2E \ Platform-specific
/ Tests \ (Detox / Patrol / XCTest)
/----------\
/ \
/ Integration \ Shared + Platform
/ Tests \ (Widget / Component tests)
/--------------------\
/ \
/ Unit Tests \ Shared logic
/ (Shared) \ (Jest / flutter_test / kotlin.test)
/----------------------------\
Testing shared logic:
- Unit test domain layer (pure functions, no platform deps)
- Mock repository interfaces for use case tests
- Test state management (Redux reducers, BLoC transitions)
Testing platform integration:
- Widget/Component tests for UI behavior
- Integration tests for native bridge calls
- Screenshot tests for visual regression
Testing end-to-end:
- Detox (React Native) or Patrol (Flutter) for full flows
- Test critical user journeys: login, purchase, onboarding
- Run on real devices in CI (BrowserStack, Firebase Test Lab)Scenario: Migrating from separate iOS/Android to cross-platform
Phase 1: Shared Logic Library
- Extract business logic into shared module (KMP or JS package)
- Keep native UI on both platforms
- Validate shared logic with tests
- Duration: 2-4 months
Phase 2: Feature-by-Feature UI Migration
- New features built cross-platform
- Existing features migrated by priority
- "Brownfield" integration (cross-platform inside native shell)
- Duration: 6-12 months
Phase 3: Full Migration
- Replace native shell with cross-platform navigation
- Migrate remaining native screens
- Decommission old native codebases
- Duration: 3-6 months
Key rule: Never big-bang rewrite. Always incremental.Before Choosing Framework:
[ ] Defined target platforms (iOS, Android, web, desktop?)
[ ] Assessed team skills and hiring market
[ ] Identified performance-critical features
[ ] Cataloged required native integrations
[ ] Checked framework maturity for your use cases
[ ] Built proof-of-concept for riskiest feature
Architecture Design:
[ ] Clean separation between UI and business logic
[ ] Repository pattern for data access abstraction
[ ] Dependency injection for testability
[ ] Offline-first data strategy defined
[ ] Navigation architecture chosen
[ ] State management approach selected
[ ] Error handling strategy (global + per-feature)
Quality:
[ ] Testing strategy defined (unit/integration/E2E split)
[ ] CI/CD pipeline for both platforms
[ ] Performance benchmarks established
[ ] Accessibility requirements met on both platforms
[ ] Platform-specific UX patterns respectedUse this skill when:
Designing or implementing cross platform architect solutions
Reviewing or improving existing cross platform architect approaches
Making architectural or implementation decisions about cross platform architect
Learning cross platform architect patterns and best practices
Troubleshooting cross platform architect-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Cross Platform Architect Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement cross platform architect for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended cross platform architect approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When cross platform architect must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
548 lines · 2,146 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Cross-Platform Architect bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for