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 54 and React Native 0.81 New Architecture.

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 New Architecture: Fabric Native Renderer and TurboModules on React Native 0.81 and Expo SDK 54.

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: Bypasses the JavaScript bridge by executing high-frequency telemetry animations on the native UI thread via Reanimated 3 SharedValues, throttled to 65ms (~15 FPS).

3. Component & UI Architecture

3.1 Expo Router File-Based Routing Topology

The application leverages Expo Router v4 (Expo SDK 54), providing type-safe, URL-driven routing modeled after file-system conventions. The routing tree is structured into clear navigation hierarchies:

• 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, 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, font asset loading, native splash dismissal, 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 (Tailwind CSS preset). 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: The useAnimatedNumber hook runs a Reanimated 3 UI worklet 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.
• 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.

4. State Management & Data Fetching Architecture

4.1 Client-Side State: Zustand Store Architecture

The application uses Zustand 4.5 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.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:

• 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 FileSystem and presented via Expo Sharing.

6.5 Subsystem 5: Push Notifications & Event Reconciliation

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

• Device Registration: NotificationServices.registerForPushNotifications() obtains the push token and registers device metadata at POST /api/v1/notifications/devices.
• 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 application mounts two global recovery overlays in app/_layout.tsx:

• NetworkStatusOverlay.tsx: Renders as a full-screen centered modal dialog with an opaque backdrop (bg-black/40). When !isConnected, it activates a blocking modal dialog with a manual "Retry Now" trigger. When isWeakConnection === true, it displays an amber status notice with non-blocking touch interaction (pointerEvents="box-none").
• SessionExpiredModal.tsx: Controlled by session-expired.store.ts. When refresh tokens expire or are rejected by the CPMS, the session teardown protocol purges all in-memory state and cache, and this modal prompts the driver to confirm re-login, executing router.replace("/(auth)/login").

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.