1. Introduction & Design Overview

1.1 Purpose & Objectives

This Software Design Description (SDD) establishes the definitive, production-grade architectural and low-level coding specification for the EV Power Mobile Application (repository evp-app, application identifier com.evpower.chargingapp). While the companion Software Requirements Specification (SRS) (docs/SRS.html, IEEE Std 830-1998) details what the application does from a functional and business perspective, this SDD defines how the software is architected, decomposed, structured, and implemented in code adhering to IEEE Std 1016-2009.

The objectives of this design document are:

• To formalize the Clean Layered Architecture governing the separation between Presentation, State Management, Domain Hooks, API Transport, and Native Persistence.
• To establish the System Context Viewpoint and external actor boundaries spanning EV Drivers, CPMS Cloud Microservices, Physical EVSE Hardware, VNPay Payment Gateway, and Push Notification Providers.
• To document the Zustand client state (6 modular stores) and TanStack React Query server caching lifecycles, including cache invalidation, background reconciliation, and multi-session keying.
• To specify the Dual-Instance Axios networking pipeline, dynamic microservice path routing, and the thread-safe 401 Refresh Token Mutex Queue with rotatedByOtherFlow race recovery.
• To provide low-level coding blueprints for the 5-step charging state machine, including real-time reanimated car silhouette liquid wave fill (buildWavePath), hardware stabilization delays, explicit driver CTA confirmation, and the AC charger battery SoC suppression fallback (BR-CHG-06).
• To serve as the canonical architectural guide for mobile engineers maintaining, extending, or refactoring the EV Power codebase on Expo SDK 57 (v57.0.22) and React Native 0.86.3 Pure Bridgeless Architecture (Fabric Renderer + TurboModules).

1.2 System Context Viewpoint & External Actor Boundaries

In compliance with IEEE Std 1016-2009 (Context Viewpoint), the EV Power Mobile Application operates as a distributed edge client interacting with multiple external actors and enterprise systems:

1.3 Scope of Software Design

The scope of this document encompasses all software modules residing within the evp-app repository:

1.4 Definitions, Acronyms & Conventions

1.5 Standards Compliance & References

• IEEE Std 1016-2009: IEEE Standard for Information Technology — Systems Design — Software Design Descriptions.
• IEEE Std 830-1998: IEEE Recommended Practice for Software Requirements Specifications (docs/SRS.html).
• OCPP 1.6J / 2.0.1: Open Charge Point Protocol JSON specification over WebSockets (CPMS to EVSE).
• RFC 7519: JSON Web Token (JWT) architecture for stateless, cryptographically signed API authorization.
• React Native Pure Bridgeless Architecture: Fabric Native Renderer and TurboModules on React Native 0.86.3, React 19.2.3, and Expo SDK 57.0.22; legacy bridge and Paper renderer permanently eliminated.

1.6 Requirements Traceability Matrix (RTM)

In accordance with IEEE Std 1016-2009 Section 5, this matrix maps all 24 Functional Requirements (FRs) and 11 Non-Functional Requirements (NFRs) defined in the companion SRS (docs/SRS.html) to concrete code symbols, screens, stores, hooks, and API clients within the evp-app repository:

1.6.1 Functional Requirements Traceability Matrix

1.6.2 Non-Functional Requirements Traceability Matrix

2. System Architecture & Design Principles

2.1 Clean Layered Architecture Overview

The EV Power Mobile Application enforces a strict 4-layer Clean Layered Architecture. Dependencies flow strictly downward from Presentation to Infrastructure; higher layers consume domain facades without knowing underlying network or persistence details:

2.2 Core Architectural Design Patterns

• Dual-Instance Axios Pattern: Separates public unauthenticated calls (e.g. login, token refresh) from protected Bearer-authenticated calls to prevent circular dependency loops during 401 token refresh.
• Mutex Refresh Queue Pattern with Concurrency Recovery: Suspends concurrent failing requests during token rotation, resolving them upon token exchange, with automatic fallback recovery via rotatedByOtherFlow if another asynchronous flow already rotated tokens.
• Multi-Session Keying Pattern: Indexes active charging sessions by physical coordinates (chargeBoxCode_connectorNo) in Zustand memory, ensuring concurrent or multi-vehicle fleet charging sessions never overwrite each other.
• SoC Suppression Guard Pattern (isAcNoSoc): Safety pattern hiding battery percentage and rendering a blurred car silhouette when charging at AC posts lacking battery telemetry, preventing driver panic from false 0% readouts.
• UI Thread Reanimated Worklets (Bridgeless Fabric): Bypasses JavaScript event queues by executing high-frequency telemetry calculations directly on the native UI thread via Reanimated 4.5.1 and standalone react-native-worklets 0.10.1 C++ runtime, throttled to 65ms (~15 FPS).
• Pure Bridgeless Runtime Pattern: Eliminates legacy bridge JSON serialization entirely; all native calls execute synchronously or via TurboModules JSI bindings. Config flag newArchEnabled: true is eliminated.
• Decoupled Navigation Pattern: Expo Router ~57.0.21 is completely decoupled from upstream @react-navigation/*, ensuring route states and navigation dispatchers remain synchronized without external hook leaking.

3. Component & UI Architecture

3.1 Expo Router File-Based Routing Topology & Decoupled Navigation

The application leverages Expo Router ~57.0.21 (Expo SDK 57), providing type-safe, URL-driven routing modeled after file-system conventions with a completely decoupled navigation architecture independent of external @react-navigation/* packages:

• Root & Onboarding Gatekeeper (app/index.tsx): Determines whether the device has completed onboarding, evaluates authentication status via useAuthStore, and routes either to /(tabs)/home (authenticated), /(auth)/login, or guest screens.
• Authentication Stack (app/(auth)/): Public authentication stack containing login.tsx, register.tsx, forgot-password.tsx, and reset-password.tsx. Note that OTP verification is handled inline as an active step within ForgotPasswordScreen.tsx and RegisterScreen.tsx rather than as an isolated standalone route.
• Authenticated Driver Tabs (app/(tabs)/): Authenticated main driver experience featuring a custom persistent floating bottom bar:
  • (tabs)/home.tsx → Driver dashboard, active charging banner, quick actions.
  • (tabs)/orders/ → Nested directory tree with _layout.tsx controller, historical charging sessions, and receipt sub-routes.
  • (tabs)/qr-scan.tsx → Raised camera QR scanner with physical connector manual entry modal.
  • (tabs)/stations.tsx → Interactive Leaflet/Map view with cluster markers, search drawer, and connector filters.
  • (tabs)/profile/ → Nested directory tree with _layout.tsx controller, ProfileUserCard responsive identity header with modular VirtualEvCard (VirtualCard), managing wallet balance, RFID charge cards, vehicles, invoices, and help center.
• Active Charging State Machine Route (app/charging/connect.tsx): Mounts screens/charging/ChargingSessionScreen.tsx, which hosts the core 5-step charging machine (PlugInStep, ConnectingStep, ChargingStep, SuccessScreen, FailedScreen). Note that app/charging-detail.tsx re-exports OrderDetailScreen (order receipt), not the active state machine.
• Guest Exploration Subsystem (screens/guests/): Provides unauthenticated discovery across 6 dedicated screens: GuestHomeScreen, GuestStationScreen, GuestSearchScreen, GuestStationDetailScreen, GuestScanGateScreen, and GuestProfileScreen.

3.2 Root Provider Tree Lifecycle (app/_layout.tsx)

The root layout component (app/_layout.tsx) manages the startup bootstrap lifecycle, Space Grotesk font asset loading, synchronous splash dismissal via expo-splash-screen ~57.0.9 (SplashScreen.hide()), Android 15 mandatory edge-to-edge windowing insets via react-native-safe-area-context ~5.7.0, and strict context provider nesting:

3.3 Custom Floating Curved SVG Tab Bar Architecture

The bottom navigation bar (app/(tabs)/_layout.tsx) features a proprietary floating SVG notch architecture with a center-cutout dome accommodating the raised QR Scanner button:

• SVG Path Math: Uses exact Quadratic Bézier (Q) and Elliptical Arc (A33,33) curves to sculpt the center dome notch dipping downwards to wrap around the 60px circular QR scan button. Zero Cubic Bézier (C) commands are utilized; NOTCH_DEPTH = 22 is declared in constants but unused in the geometric path math.
• Top Rim Active Indicator: A 4px absolute bar (Animated.View style={{ height: 4, position: 'absolute', top: 0 }}) glides along the top edge of the tab bar using Animated.spring(indicatorPosition, { tension: 65, friction: 10, useNativeDriver: true }).
• QR Tab Transparency: When the driver taps the center QR button (tab index 2), the indicator's opacity smoothly fades to 0 via Animated.timing(indicatorOpacity, { toValue: 0, duration: 200 }), preventing visual artifacts beneath the elevated camera button.

3.4 Design System, Tokens & Styling Architecture

The design system is constructed on NativeWind v4 (nativewind@^4.2.7) backed by react-native-css-interop@0.2.7 and tailwindcss@3.4.19. This toolchain is certified against React 19.2.3 and React Native 0.86.3 Fabric without requiring NativeWind v5 breaking syntax modifications. Styling tokens are dynamically harmonized across Dark and Light modes through ThemeContext.tsx:

3.5 Micro-Interactions & High-Performance Animations

To maintain a fluid 60 FPS experience on mobile devices during intensive live telemetry polling:

• CarProgressContainer Liquid Wave Silhouette: Rather than a generic circular progress ring, CarProgressContainer.tsx renders an SVG side-profile car silhouette with an animated liquid wave clipping fill (buildWavePath). Reanimated shared values drive sinusoidal horizontal translation and vertical fill height matching batteryPct.
• Throttled Reanimated UI Worklet (Fabric Engine): The useAnimatedNumber hook runs a React Native Reanimated 4.5.1 worklet powered by the standalone react-native-worklets 0.10.1 C++ engine. It is throttled to 65ms (~15 FPS) via useAnimatedReaction, interpolating numeric metrics (kwh, amount in EVP, batteryPct) over 1,200 ms with cubic easing, completely offloading the JS thread. Babel AST transformations are automatically injected by babel-preset-expo@57.0.11; manual worklet plugin registration is prohibited.
• Background Battery Conservation: The useAppActive() hook detects when the mobile OS transitions the app to the background (or another tab). When inactive, UI animations are immediately paused to conserve CPU cycles and battery.

3.6 Modular Profile Identity & VirtualCard Architecture (ProfileUserCard & VirtualEvCard)

In accordance with the Single Responsibility Principle (SRP) and component modularity standards, the driver profile header presentation was refactored to cleanly decouple user account metadata from the digital wallet card presentation:

4. State Management & Data Fetching Architecture

4.1 Client-Side State: Zustand Store Architecture

The application uses Zustand 5 (v5.0.15) for client-side state management. State is divided across 6 dedicated, loosely-coupled domain stores:

4.2 Multi-Session Keying & State Isolation

A critical architectural pattern in stores/charging-store.ts is the Multi-Session Keying model. Instead of storing a single global active session, sessions are stored in an indexed dictionary keyed by physical hardware coordinates:

/** Unique composite session key for physical charger connector */
export function makeSessionKey(chargeBoxCode: string, connectorNo: number): string {
  return `${chargeBoxCode}_${connectorNo}`;
}

export interface ChargingSession {
  chargeBoxCode: string;
  connectorNo: number;
  stationName: string;
  connectorLabel: string;
  startedAt: number;        // Epoch millisecond timestamp
  elapsedSeconds: number;
  kwh: number;
  batteryPct: number;
  transactionId: number | null;
  hasNavigatedOnStop: boolean;
  hasCompleted: boolean;
}

Architectural Invariant: The canonical delimiter is underscore (${chargeBoxCode}_${connectorNo}). For backward compatibility with legacy socket payloads, stores/charging-store.ts:140 also safely falls back to colon splitting if encountered. This dictionary indexing guarantees that concurrent charging sessions (e.g. multi-vehicle fleet accounts) never overwrite each other's live metrics.

4.3 Server-Side Cache: TanStack React Query Configuration

Remote server state is managed through TanStack React Query v5 (libs/query/client.ts). The global client is configured with strict staleness and garbage collection policies tailored for mobile networks:

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 1,                          // Fail fast to allow light retry interceptor to handle 5xx
      staleTime: 30000,                  // 30 seconds: prevents redundant network requests
      gcTime: 300000,                    // 5 minutes: cache retention in memory
      refetchOnReconnect: "always",       // Immediate refetch when network comes online
      refetchOnMount: true,
      refetchOnWindowFocus: false,       // Suppressed on React Native mobile clients
    },
  },
});

4.4 Unified Session Teardown Protocol

When authentication tokens expire or the driver explicitly logs out, a hard session invalidation occurs. To prevent stale data leakage across driver sessions, stores/auth.store.ts executes a synchronous teardown protocol:

Calling clearSessionState() atomically executes:

• useAuthStore.getState().clear() → Purges user entity and auth status.
• useNotificationStore.getState().resetNotifications() → Clears unread counts and cached alerts.
• useProfileStore.getState().resetProfile() → Resets balance and personal profiles.
• useChargingStore.getState().clearAllSessions() → Wipes all active charging timers and telemetry.
• queryClient.clear() → Purges 100% of cached query responses from memory.

5. Networking, API Client & 401 Mutex Architecture

5.1 Dual-Instance Axios Pattern

The networking layer (api/client.ts) instantiates two distinct Axios instances:

1. Public Client (publicClient): Used exclusively for unauthenticated endpoints (login, register, forgot password, and token refresh). It has no Bearer token interceptor, eliminating circular dependency deadlocks.
2. Protected Client (protectedClient): Injects Authorization: Bearer <token> headers, monitors responses for 401 UNAUTHORIZED status, and interfaces with the token refresh mutex queue.

5.2 Dynamic Microservice Path Construction

Backend services are structured as microservices under unified API gateway prefixes. api/client.ts dynamically builds service base URLs according to the target domain module:

5.3 Thread-Safe 401 Refresh Mutex Queue Sequence

When access tokens expire, concurrent protected requests risk triggering a stampede of refresh calls. api/interceptors.ts enforces a thread-safe Mutex Queue:

The mutex implements 4 critical engineering invariants:

1. Single-Flight Refresh: While isRefreshing = true, subsequent failing 401 calls push their promise resolve/reject handlers into failedQueue[].
2. Stale Response Guard (_authSessionVersion): If a logout occurs while a refresh call is inflight, the response version is compared against authSessionVersion. Stale refresh results are safely discarded.
3. Single-Fire Session Expired Notification: If token refresh fails with 401/403, hasNotifiedSessionExpired ensures only one modal dialog is presented, preventing alert stacking.
4. Concurrent Rotation Recovery (rotatedByOtherFlow): If the refresh attempt fails with 400/401/403, the interceptor checks SecureStore (api/interceptors.ts:275-285). If another concurrent flow already rotated the refresh token (refreshTokenUsed !== latestRefreshToken), the queue is resolved with latestAccessToken and retried without dropping the session.

5.4 Network Resiliency & Weak Network Detection

The networking stack integrates with @react-native-community/netinfo via NetworkContext.tsx:

• Connection State: Distinguishes between completely offline (isConnected === false) and weak/unstable connectivity (isWeakConnection === true, e.g. 2G or poor cellular handoff).
• Idempotent Safe Retries: Read-only HTTP GET requests are automatically retried once on transient socket timeouts (ECONNABORTED). State-mutating POST/PATCH operations are never retried automatically to prevent duplicate transactions.

5.5 Localized Error Translation Pipeline & PII Redaction

Backend errors return standardized error codes (e.g. INVALID_CREDENTIALS, WALLET_INSUFFICIENT_BALANCE). The interceptor transforms these into user-facing localized messages using api/errors.ts:

• EXCLUDED_CODES Proxy Guard: The code "UNAUTHORIZED" is explicitly excluded from the i18n error code translation proxy. This ensures that 401 errors fall through directly to the token refresh mutex queue rather than prematurely rejecting with a localized error string.
• Sensitive Credential & Token Redaction: To satisfy NFR-SEC-02, maskToken and sanitizeAuthPayload redact bearer tokens, refresh tokens, passwords, and PINs from debug console logs (e.g., displaying eyJhbGci...4f8a).

6. Detailed Subsystems Coding Design (LLD)

6.1 Subsystem 1: 5-Step EV Charging Session State Machine

The core business value of EV Power resides in screens/charging/ChargingSessionScreen.tsx (mounted at app/charging/connect.tsx). The charging lifecycle is governed by a 5-step finite state machine:

The state machine transitions follow strict hardware and safety guards:

6.1.1 StoppingChargeOverlay Component Architecture & Fabric In-Tree Overlay Pattern

In Step 4 (terminating) of the charging lifecycle, the application executes a high-stakes, two-phase settlement sequence. During this interval, the hardware contactor is opening, the CPMS is calculating final energy meters, and premature driver navigation or concurrent touch interactions could produce an orphaned session or corrupted billing record. To guarantee uncompromising reliability and visual excellence on modern mobile operating systems, StoppingChargeOverlay.tsx was re-engineered from a legacy native modal into an In-Tree Full-Screen Absolute Viewport Overlay.

6.2 Subsystem 2: RFID Charge Card Management (charge-card)

Physical RFID charging card management is mounted at app/charging-card.tsx rendering screens/profile/MyVouchersScreen.tsx:

• Status Filter Tabs: Tabbed segmented control (ChargeCardStateTabs.tsx) filters cards by status: ALL, ACTIVE (valid point lots), EXPIRING_SOON (≤7 days remaining), USED_UP (zero balance), and EXPIRED.
• Scratch Card PIN Activation: Modal dialog accepts the 16-character serial and scratch PIN, dispatching POST /api/v1/wallet/cards/activate via WalletServices.redeemChargeCard(), immediately invalidating ['my-charge-cards'] and ['profile'] caches.
• Point Lot Representation: Each card represents a promotional point voucher lot with face value (facePoint), remaining points (pointRemaining), and expiry timestamp (pointExpireAt).

6.3 Subsystem 3: EVP Digital Wallet & VNPay Integration

Platform transactions strictly observe the currency conversion rate 1 EVP = 1,000 VND:

• Wallet Entrypoint via VirtualEvCard: Driver views real-time EVP balance and outstanding debt points on the modular <VirtualEvCard /> in ProfileUserCard. Tapping the full-width "Nạp tiền" (Top Up) CTA navigates directly to app/(tabs)/profile/top-up.tsx.
• Top-Up Creation: Driver selects EVP point package; app dispatches POST /api/v1/wallet/topups receiving VNPay checkout URL (paymentUrl) and topupId.
• Embedded WebView Checkout: Payment is processed inside an in-app <TopupPaymentWebView /> modal, avoiding external browser switches and preserving mobile context.
• Reactive Push Settlement: Upon VNPay completion, backend issues a TOPUP_SUCCESS push notification. The app invalidates ['topup-status', id], refetches GET /api/v1/wallet/topups/{id}, and refreshes useProfileStore balance.

6.4 Subsystem 4: Electronic VAT Invoices & PDF Streaming

Corporate and individual tax invoice management is implemented under app/invoice/:

• Invoice Profiles: Managed via InvoiceProfileServices (POST /api/v1/invoice-profiles) supporting Tax Code (Mã số thuế), Company Legal Name, and registered Tax Address.
• Binary PDF Streaming: Invoice PDF downloads invoke InvoiceServices.downloadInvoice({ id }), dispatching GET /api/v1/invoices/{id}/download with responseType: "arraybuffer" and header Accept: application/pdf. The raw buffer is cached via expo-file-system ~57.0.7 using the modern Paths.cache.uri API and presented via Expo Sharing ~57.0.19.

6.5 Subsystem 5: Push Notifications & Event Reconciliation

Real-time updates are mediated via Expo Push Notifications (api/services/notification.ts):

• Config Plugin & Device Registration: Handled by expo-notifications ~57.0.18 declared as a native plugin in app.json (legacy root notification configuration dropped). NotificationServices.registerForPushNotifications() obtains the push token, registers metadata at POST /api/v1/notifications/devices, and cleans up listeners using sub.remove().
• Foreground State Reconciliation: In app/_layout.tsx, when an ORDER_CREATED notification arrives, the app invokes ChargingServices.getChargingSessionActive() and updates chargingStore.restoreSessions(), reactively displaying active sessions in <ActiveSessionList /> on HomeScreen.
• Background Notification Route Gap: NotificationServices.addNotificationResponseReceivedListener is provided for tapping background notifications; mounting it in root layout is scheduled for future deep-linking routing.

6.6 Subsystem 6: Vehicle Fleet Garage & Spending Limits (vehicles)

Vehicle management is implemented under app/vehicle/ and screens/vehicle/:

• Garage Listing & Details: useVehiclesQuery fetches user EVs from GET /api/v1/vehicles.
• Per-Session Spending Cap: Corporate fleet accounts can set session spending limits via VehicleServices.updateVehicle(id, { label, maxPointPerSession }) dispatching PATCH /api/v1/vehicles/{id}, preventing runaway vehicle charging debt.

7. Storage & Security Architecture

7.1 Multi-Tier Storage Architecture

Data persistence in the EV Power mobile app is segregated into three distinct isolation tiers based on data sensitivity and lifecycle characteristics:

1. Tier 1: Hardware-Backed Encrypted Storage (Expo SecureStore): Utilizes hardware keystores (iOS Keychain with kSecAttrAccessibleAfterFirstUnlock and Android Keystore with AES-256-GCM encryption). Only authentication and session-critical secrets are persisted here.
2. Tier 2: Non-Sensitive Persistent Storage (AsyncStorage / app-storage.ts): Lightweight, unencrypted key-value storage used for UI theme modes, language selections, dismissible tutorial flags, and brute-force lockout hashes.
3. Tier 3: In-Memory Volatile State (Zustand / React Query Cache): All active charging telemetry, real-time prices, and temporary user inputs reside strictly in RAM and are automatically purged upon application termination or session logout.

7.2 Storage Boundary Catalog

In accordance with IEEE Std 1016 Data Persistence Viewpoint, the complete catalog of persistent storage keys in the evp-app client is detailed below:

8. Error Handling, Resilience & Telemetry Fallback

8.1 Multi-Tier Exception Handling Framework

Errors propagate through a 4-tier funnel designed to prevent unhandled promise rejections and network failures:

8.2 Live Telemetry Offline Degradation & Mathematical Utility

During active charging sessions, the mobile client must remain resilient when traversing areas with poor or intermittent cellular connectivity (e.g. underground parking basements):

• Actual Runtime Degradation: If telemetry polling fails due to connection loss, useChargingStep.ts continues ticking the client-side elapsed timer clock (setInterval(syncElapsedSeconds, 1000)). The instrumentation metrics (energyWh, socPercent, estimatedPoint) remain frozen at their last authoritative server values until connectivity is restored and polling resumes.
• Dead-Reckoning Mathematical Model: stores/charging-store.ts defines a mathematical estimation helper (getChargingProgress) based on nominal charger output (CHARGER_POWER_KW = 50) and battery capacity (BATTERY_CAPACITY_KWH = 75). This module currently serves as a standalone calculation utility and is slated for active UI integration in a future release with an explicit driver notification badge.

8.3 Global Overlays & Modal Recovery Workflows

The EV Power architecture distinguishes between two specialized overlay tiers based on lifecycle scope, hardware interaction depth, and rendering performance requirements:

9. Testing, Verification & Coding Standards

9.1 TypeScript Typing & Architectural Boundaries

• Strict Typing: Zero usage of unconstrained any in domain modules. Generic typing is enforced on all API responses (this.api<T>()).
• Layered Type Separation: Domain entities reside under types/<domain>/*.types.ts (e.g. types/charge-card/, types/vehicle/), while remote REST service DTO payloads reside under types/services/*.types.ts.
• Immutability: State updates in Zustand stores utilize spread patterns or functional updaters, ensuring strict referential equality checks for React render optimizations.

9.2 Unit & Integration Testing Strategy

• Zustand Store Unit Tests: Verify store actions, multi-session key mapping, duration calculations, and atomic session teardown in isolation with mocked storage engines.
• Interceptor Mutex Tests: Test parallel 401 token refresh queue concurrency, ensuring only 1 refresh call is dispatched, failed requests are replayed with new tokens, and rotatedByOtherFlow recovers without session loss.
• State Machine Guard Tests: Validate that useChargingStep strictly enforces the explicit CTA tap in Step 1, the 1,800 ms hardware delay in Step 2, and the isAcNoSoc suppression guard on AC charging sessions.

9.3 Mocking & Simulation Infrastructure

• Axios Mock Adapter: Simulates REST endpoints for testing offline queuing and token refresh without live backend dependencies.
• NetInfo Mocking: Tests NetworkStatusOverlay behaviors across offline, cellular 2G (weak), and high-speed Wi-Fi states.

9.4 Continuous Native Generation & Multi-Gate Verification Protocol

Following the Expo SDK 57 upgrade, native project directories (ios/, android/) are governed by Continuous Native Generation (CNG). Every release and refactor must satisfy a strict 5-gate verification sequence prior to merge:

10. Expo SDK 57 Master Dependency Matrix & Architectural Evolution

10.1 Master Dependency Version Matrix (58 Packages)

The EV Power Mobile Application was migrated from Expo SDK 54 (React Native 0.81.5, React 19.1.0) to Expo SDK 57 (v57.0.22, React Native 0.86.3, React 19.2.3). All 58 production and development dependencies are synchronized according to bundledNativeModules.json and peer-dependency satisfaction:

10.2 Architectural Breaking Changes & Concrete Refactoring

The SDK 57 upgrade addressed several critical runtime and compilation breaking changes across the codebase:

• Decoupled Expo Router & useIsFocused (10 Code Locations): In SDK 57, Expo Router decoupled itself from @react-navigation/*. Direct imports of useIsFocused from @react-navigation/native bypassed Expo Router's route state, causing desynchronization. All 10 application files (ChargingSessionScreen, SetupScreen, QRScanScreen, StationMapScreen, useActiveSessionItem, useChargingSession, useAppActive, HomeStationMap, useStationMap, StationLocationMap) were repointed to import { useIsFocused } from "expo-router".
• Android View Flattening & Map Marker Stabilization: On Android Fabric, Google Maps captures canvas software snapshots of child views inside <Marker>. Fabric's View Flattening aggressively optimized away intermediate <View> wrappers, collapsing them to 0x0 pixels. Adding collapsable={false} to StationMarker.tsx forces Android view generation, restoring charging pins on Google Maps.
• StoppingChargeOverlay Modal Restructure & In-Tree Fabric Port: Native React Native <Modal> spawns an isolated secondary native Window (android.app.Dialog on Android, UIWindow on iOS), breaking Android 12+ Fabric expo-blur (RenderEffect / dimezisBlurView) due to cross-window surface isolation, and producing vertical offset errors under Android 15 edge-to-edge insets. StoppingChargeOverlay was refactored into an in-tree full-screen absolute viewport overlay (StyleSheet.absoluteFillObject, zIndex: 9999, elevation: 9999) mounted as a sibling to <SafeAreaView> in ChargingSessionScreen.tsx. It integrates dual-layer anti-fog contrast scrimming, dead-centered card geometry (minWidth: 220, maxWidth: 240, rounded-3xl, Lottie spinner), full pointer event trapping, and atomic navigation lockdown (BackHandler, gestureEnabled: false, beforeRemove interception).
• Modern FileSystem Migration: Refactored (FileSystem as any).cacheDirectory in SettingsScreen.tsx to the official Paths.cache.uri API from expo-file-system ~57.0.7.
• TypeScript Compilation Integrity: Restored missing const unitPrice = unitPriceStr ? Number(unitPriceStr) : undefined; at hooks/useChargingSession.ts:59, ensuring npm run typecheck exits 0 without errors.

10.3 Mobile OS Deployment Baselines & Rollback Protocol

In the event of an unforeseen production blocker on physical hardware, rollback to the SDK 54 baseline is achieved via:

# 1. Revert package configs and working tree
git checkout main -- package.json pnpm-lock.yaml app.json app.config.ts
git checkout main -- components/ hooks/ screens/

# 2. Reinstall frozen lockfile
pnpm install --frozen-lockfile

# 3. Clean Continuous Native Generation
npx expo prebuild --clean

# 4. Diagnostic verification
npx expo-doctor && npm run typecheck