Implement Dashboard and Transaction History

[CodeByMAB]

Epic Reference

Part of Epic: Breez SDK Integration for Expo App (epic:97fd7dcb-10ec-46a8-b681-b2805eb0eb56)
SRS Spec: spec:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/a8f8bef7-d1c5-4113-a9ad-6092120bfe76

Overview

Implement the main Dashboard (wallet overview, Lightning balance, quick actions: Send, Receive, Withdraw, Scan) and unified Transaction History (Lightning send/receive, withdrawals, filters, search, details). Align with SRS wireframes (FR-UI-001, FR-HIST-001, FR-HIST-002).

Related SRS Requirements: FR-UI-001, FR-HIST-001, FR-HIST-002, Section 5 wireframes

Tasks

• Dashboard: Display total Lightning balance (from Breez SDK node state)
• Dashboard: Recent transactions (last 5); quick action buttons Send, Receive, Withdraw, Scan
• Dashboard: Connection status; inbound/outbound liquidity summary; channel count
• Dashboard loads within 1 second (AC-UI-001-05)
• Transaction list: All types (Lightning sent/received, withdrawals, pending); type, amount, date, status
• Filter by type (Lightning, withdrawal, all); search by description or amount; infinite scroll (e.g. 50 per page)
• Transaction details: Withdrawal → destination address, amount, fee, confirmations, txid; Lightning → invoice, amount, fee, preimage, description
• Copy/share transaction details; link to block explorer for withdrawals (e.g. mempool.space)
• Data source: Breez SDK transaction history; cache in local SQLite for performance

Acceptance Criteria

• AC-UI-001-01 to 05: Balance, recent 5 tx, quick actions, connection status, load <1s
• AC-HIST-001-01 to 05: List all tx, type/amount/date/status, filter, search, pagination
• AC-HIST-002-01 to 05: Withdrawal details (address, fee, confirmations, txid); Lightning details; copy; share; block explorer link

Wireframes

See SRS Section 5 (FR-UI-001 Dashboard wireframe) for layout reference.

Dependencies

• Setup Expo Project with Breez SDK Integration #1 Setup Expo Project with Breez SDK Integration
• Implement Wallet Creation and Restoration #2 Implement Wallet Creation and Restoration
• Initialize Breez SDK and Lightning Node #3 Initialize Breez SDK and Lightning Node
• Implement Lightning Payment Operations #4 Implement Lightning Payment Operations
• Implement Withdrawal to External Bitcoin Address #5 Implement Withdrawal to External Bitcoin Address

---

Ticket ID: ticket:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/08efc6d9-1116-4964-a565-6aa01ca90060

[traycerai]

Plan

Observations

The codebase is in early stages with only documentation (SRS and BRS) available. The SRS provides detailed wireframes, functional requirements (FR-UI-001, FR-HIST-001, FR-HIST-002), data models, and acceptance criteria. The app is a Lightning-only wallet using Breez SDK Spark for nodeless Lightning operations. Key dependencies include Breez SDK for transaction history (listPayments) and node state (getInfo), SQLite for local caching, and Expo/React Native for the UI framework. The dashboard must load within 1 second and display real-time Lightning balance, liquidity metrics, and recent transactions.

Approach

The implementation follows a layered architecture: (1) Data layer with Breez SDK integration and SQLite caching, (2) State management for real-time updates, (3) UI components for Dashboard and Transaction History screens. The Dashboard will fetch node state from Breez SDK to display balance, liquidity, and connection status, while recent transactions come from cached SQLite data. The Transaction History screen implements filtering, search, and pagination with infinite scroll. Both screens leverage Breez SDK events for real-time updates and maintain local SQLite cache for performance, ensuring the dashboard loads under 1 second as required.

Implementation Steps

1. Data Layer Setup

1.1 SQLite Database Configuration

• Install and configure expo-sqlite or react-native-sqlite-storage for local database management
• Create database initialization module at file:src/database/init.ts
• Implement the transactions table schema as defined in file:docs/SRS.md (lines 2568-2590):
  • Fields: id, type, status, amount_sats, fee_sats, description, timestamp, confirmations, txid, payment_hash, preimage, invoice, destination_address
  • Indexes on timestamp (DESC), type, and status for query performance
• Implement the channels table schema (lines 2592-2609)
• Add database encryption using SQLCipher for security compliance
• Create database migration system for future schema updates

1.2 Breez SDK Integration Service

• Create Breez SDK service module at file:src/services/breezSdk.ts
• Implement getNodeState() method wrapping Breez SDK's getInfo() to retrieve:
  • Lightning balance (local balance in channels)
  • Inbound liquidity (capacity to receive)
  • Outbound liquidity (capacity to send)
  • Connected peers count
  • Sync status
• Implement fetchTransactionHistory() method using Breez SDK's listPayments() with pagination support
• Add event listener registration for real-time updates:
  • paymentReceived - update balance and transaction list
  • paymentSent - update balance and transaction list
  • nodeStateChanged - refresh dashboard metrics
  • syncComplete - update sync status
• Implement error handling with retry logic for SDK operations

1.3 Transaction Cache Manager

• Create cache manager at file:src/services/transactionCache.ts
• Implement syncTransactionsToCache() to fetch from Breez SDK and store in SQLite
• Add getCachedTransactions() with filtering and pagination:
  • Support filters: type (lightning_send, lightning_receive, withdrawal, all)
  • Support search by description or amount
  • Implement pagination with 50 items per page
  • Sort by timestamp descending
• Implement getRecentTransactions(limit: number) for dashboard (last 5)
• Add cache invalidation strategy triggered by SDK events
• Implement background sync to keep cache updated

2. State Management

2.1 Dashboard State

• Create dashboard state store at file:src/store/dashboardStore.ts (using Zustand, Redux, or Context API based on project conventions)
• Define state shape:
  • lightningBalance: number
  • inboundLiquidity: number
  • outboundLiquidity: number
  • channelCount: number
  • connectionStatus: 'connected' | 'disconnected' | 'syncing'
  • recentTransactions: Transaction[]
  • isLoading: boolean
  • lastUpdated: number
• Implement actions:
  • loadDashboardData() - fetch from cache and SDK
  • refreshBalance() - update balance from SDK
  • updateFromEvent(event) - handle SDK events
• Add memoized selectors for derived data

2.2 Transaction History State

• Create transaction history store at file:src/store/transactionStore.ts
• Define state shape:
  • transactions: Transaction[]
  • filters: { type: string, search: string }
  • pagination: { page: number, hasMore: boolean }
  • isLoading: boolean
  • selectedTransaction: Transaction | null
• Implement actions:
  • loadTransactions(filters, page) - fetch from cache
  • searchTransactions(query) - filter by description/amount
  • filterByType(type) - filter by transaction type
  • loadMore() - pagination support
  • selectTransaction(id) - for details view
  • refreshTransactions() - sync from SDK

3. Dashboard Screen Implementation

3.1 Dashboard Component Structure

• Create main dashboard screen at file:src/screens/DashboardScreen.tsx
• Follow wireframe layout from file:docs/SRS.md (lines 910-1024)
• Component hierarchy:
  • DashboardScreen (container)
    • BalanceHeader - displays Lightning balance with network badge
    • QuickActions - Send, Receive, Withdraw, Scan buttons
    • RecentActivity - last 5 transactions
    • StatusBar - inbound/outbound liquidity, channel count

3.2 Balance Header Component

• Create file:src/components/dashboard/BalanceHeader.tsx
• Display total Lightning balance from dashboardStore.lightningBalance
• Show network badge (Testnet/Mainnet) from wallet settings
• Implement unit conversion (sats ↔ BTC) based on user preference
• Add optional fiat conversion display (≈ $XXX USD) using cached exchange rates
• Apply gradient background styling as per wireframe
• Ensure text is accessible with proper contrast ratios

3.3 Quick Actions Component

• Create file:src/components/dashboard/QuickActions.tsx
• Implement 4 action buttons in flex layout:
  • Send - navigate to Send Payment screen
  • Receive - navigate to Receive Payment screen
  • Withdraw - navigate to Withdrawal screen
  • Scan - open QR scanner with auto-detection
• Use icon library (e.g., react-native-vector-icons) for consistent icons
• Add haptic feedback on button press
• Implement navigation using React Navigation

3.4 Recent Activity Component

• Create file:src/components/dashboard/RecentActivity.tsx
• Display last 5 transactions from dashboardStore.recentTransactions
• Each transaction item shows:
  • Icon based on type (⚡ Lightning, 🔗 Withdrawal)
  • Description text
  • Relative timestamp (e.g., "2 hours ago")
  • Amount with +/- indicator and color coding
• Add "See All" link navigating to Transaction History screen
• Implement empty state when no transactions exist
• Use FlatList for rendering with keyExtractor

3.5 Status Bar Component

• Create file:src/components/dashboard/StatusBar.tsx
• Display 3 metrics in equal-width columns:
  • Inbound: dashboardStore.inboundLiquidity formatted in sats
  • Outbound: dashboardStore.outboundLiquidity formatted in sats
  • Channels: dashboardStore.channelCount with "active" label
• Apply background color and border styling per wireframe
• Update in real-time when node state changes

3.6 Dashboard Data Loading

• Implement useEffect hook in DashboardScreen to load data on mount
• Call dashboardStore.loadDashboardData() which:
  1. Loads recent transactions from SQLite cache (fast)
  2. Fetches node state from Breez SDK
  3. Updates state with combined data
• Implement pull-to-refresh functionality using RefreshControl
• Add loading skeleton/shimmer while data loads
• Ensure total load time is under 1 second (AC-UI-001-05)
• Subscribe to Breez SDK events for real-time updates

4. Transaction History Screen Implementation

4.1 Transaction List Component

• Create main screen at file:src/screens/TransactionHistoryScreen.tsx
• Follow wireframe layout from file:docs/SRS.md (lines 1370-1501)
• Component hierarchy:
  • TransactionHistoryScreen (container)
    • SearchBar - search input with icon
    • FilterTabs - All, Lightning, Withdrawals, Pending
    • TransactionList - grouped by date with infinite scroll

4.2 Search and Filter Bar

• Create file:src/components/transactions/SearchBar.tsx
• Implement search input with debounced onChange (300ms delay)
• Call transactionStore.searchTransactions(query) on input change
• Search matches against transaction description and amount
• Add clear button (X) to reset search
• Create file:src/components/transactions/FilterTabs.tsx
• Implement horizontal scrollable tabs: All, ⚡ Lightning, 🔗 Withdrawals, ⏳ Pending
• Highlight active filter with background color change
• Call transactionStore.filterByType(type) on tab press

4.3 Transaction List with Grouping

• Create file:src/components/transactions/TransactionList.tsx
• Group transactions by date (Today, Yesterday, specific dates)
• Use SectionList for grouped rendering with date headers
• Implement infinite scroll using onEndReached callback:
  • Trigger transactionStore.loadMore() when reaching bottom
  • Load next 50 transactions from cache
  • Show loading indicator at bottom while fetching
• Each transaction item component (TransactionItem.tsx):
  • Icon with background color based on type (lightning/onchain/pending)
  • Description and metadata (time, type, confirmations)
  • Amount with color coding (green for positive, black for negative)
  • Status badge (Confirmed/Pending)
• Add pull-to-refresh to sync from Breez SDK
• Implement empty state when no transactions match filters

4.4 Transaction Details Screen

• Create file:src/screens/TransactionDetailsScreen.tsx
• Display different fields based on transaction type:
  • Withdrawal (AC-HIST-002-01):
    • Destination address (external Layer 1 address)
    • Amount in sats
    • On-chain fee
    • Confirmations count
    • Transaction ID (txid)
  • Lightning (AC-HIST-002-02):
    • Invoice (Bolt11 string)
    • Amount in sats
    • Routing fee
    • Payment preimage (if available)
    • Description
    • Payment hash
• Implement copy functionality for each field:
  • Use Clipboard API from React Native
  • Show toast notification on successful copy
• Add share button to share transaction details as text
• For withdrawals, add "View on Explorer" button:
  • Link to mempool.space with txid
  • Open in external browser or in-app WebView
• Style with card layout and proper spacing

5. Utility Functions and Helpers

5.1 Formatting Utilities

• Create file:src/utils/formatters.ts
• Implement formatSats(amount: number, unit: 'sats' | 'BTC'):
  • Format with thousands separators
  • Handle BTC conversion (1 BTC = 100,000,000 sats)
  • Return formatted string
• Implement formatTimestamp(timestamp: number):
  • Return relative time for recent transactions ("2 hours ago", "Yesterday")
  • Return formatted date for older transactions ("Feb 4, 2026")
• Implement formatAddress(address: string, truncate: boolean):
  • Truncate long addresses for display (bc1q...xyz)
  • Return full address when needed
• Add formatTransactionType(type: string) for display labels

5.2 Navigation Helpers

• Create file:src/navigation/DashboardNavigator.tsx
• Configure stack navigator with screens:
  • Dashboard (initial route)
  • Send Payment
  • Receive Payment
  • Withdraw
  • Transaction History
  • Transaction Details
• Set up navigation params typing for type safety
• Configure header styles consistent with wireframes

5.3 Constants and Configuration

• Create file:src/constants/transactions.ts
• Define transaction type enums matching data model
• Define status enums (pending, confirmed, failed)
• Set pagination constants (PAGE_SIZE = 50)
• Define block explorer URLs (testnet/mainnet)

6. Performance Optimizations

6.1 Dashboard Performance

• Implement React.memo for all dashboard components to prevent unnecessary re-renders
• Use useMemo for expensive calculations (balance conversions, date formatting)
• Implement virtualization for recent transactions list (though only 5 items)
• Cache node state in memory with TTL (time-to-live) of 5 seconds
• Prefetch recent transactions on app launch in background
• Use skeleton loaders instead of spinners for better perceived performance

6.2 Transaction List Performance

• Use FlatList/SectionList with proper optimization props:
  • windowSize={10} - render 10 screens worth of content
  • maxToRenderPerBatch={10} - render 10 items per batch
  • updateCellsBatchingPeriod={50} - batch updates every 50ms
  • removeClippedSubviews={true} - unmount off-screen items
• Implement getItemLayout for consistent item heights (skip measurement)
• Use keyExtractor with stable IDs (transaction.id)
• Memoize transaction item components
• Implement database query optimization with proper indexes
• Add request debouncing for search (300ms)

6.3 Caching Strategy

• Implement two-tier caching:
  • Memory cache: Recent transactions and node state (fast access)
  • SQLite cache: Full transaction history (persistent)
• Set cache invalidation rules:
  • Invalidate on SDK payment events
  • Refresh every 30 seconds in background
  • Force refresh on pull-to-refresh
• Implement optimistic updates for better UX:
  • Update UI immediately on user action
  • Sync with SDK in background
  • Rollback on failure

7. Real-time Updates

7.1 SDK Event Listeners

• Register event listeners in file:src/services/breezSdk.ts
• Handle paymentReceived event:
  • Add new transaction to cache
  • Update dashboard balance
  • Show notification to user
  • Refresh transaction list if visible
• Handle paymentSent event:
  • Update transaction status in cache
  • Update dashboard balance
  • Refresh transaction list
• Handle nodeStateChanged event:
  • Update balance, liquidity, channel count
  • Refresh dashboard metrics
• Implement event queue to batch rapid updates

7.2 State Synchronization

• Use event emitter pattern to propagate SDK events to UI
• Implement global event bus at file:src/services/eventBus.ts
• Subscribe to events in dashboard and transaction screens
• Debounce rapid updates to prevent UI thrashing
• Ensure state consistency between cache and SDK

8. Error Handling and Edge Cases

8.1 Error Handling

• Implement error boundary component for crash recovery
• Add try-catch blocks around all SDK calls
• Display user-friendly error messages for common failures:
  • Network disconnection
  • SDK initialization failure
  • Database errors
• Implement retry logic with exponential backoff for transient errors
• Log errors to analytics service for monitoring

8.2 Edge Cases

• Handle empty states:
  • No transactions yet (show onboarding message)
  • No search results (show "No results found")
  • No network connection (show offline indicator)
• Handle pending transactions:
  • Show pending status badge
  • Update when confirmed via SDK event
  • Handle failed transactions
• Handle large transaction lists:
  • Implement pagination to avoid memory issues
  • Lazy load transaction details
• Handle concurrent updates:
  • Use database transactions for atomic updates
  • Implement optimistic locking if needed

9. Testing Considerations

9.1 Component Testing

• Test dashboard components render correctly with mock data
• Test transaction list filtering and search functionality
• Test pagination and infinite scroll behavior
• Test pull-to-refresh functionality
• Verify navigation between screens

9.2 Integration Testing

• Test Breez SDK integration with mock SDK responses
• Test SQLite cache operations (CRUD)
• Test event listener registration and handling
• Test state synchronization between cache and SDK
• Verify performance meets 1-second load time requirement

9.3 Data Testing

• Test transaction data model validation
• Test database migrations
• Test cache invalidation logic
• Test data formatting utilities
• Verify data persistence across app restarts

Architecture Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant Store
    participant Cache
    participant BreezSDK
    
    User->>Dashboard: Open App
    Dashboard->>Store: loadDashboardData()
    Store->>Cache: getCachedTransactions(5)
    Cache-->>Store: Recent 5 transactions
    Store->>BreezSDK: getInfo()
    BreezSDK-->>Store: Node state (balance, liquidity)
    Store-->>Dashboard: Update UI
    Dashboard-->>User: Display (< 1s)
    
    BreezSDK->>Store: paymentReceived event
    Store->>Cache: syncTransactionsToCache()
    Store-->>Dashboard: Update balance & transactions
    Dashboard-->>User: Real-time update
    
    User->>Dashboard: Tap "See All"
    Dashboard->>User: Navigate to Transaction History
    User->>Store: Filter by Lightning
    Store->>Cache: getCachedTransactions(filter, page)
    Cache-->>Store: Filtered transactions
    Store-->>User: Display filtered list
    
    User->>Store: Scroll to bottom
    Store->>Cache: getCachedTransactions(page+1)
    Cache-->>Store: Next 50 transactions
    Store-->>User: Append to list

Loading

Component Structure

src/
├── screens/
│   ├── DashboardScreen.tsx
│   ├── TransactionHistoryScreen.tsx
│   └── TransactionDetailsScreen.tsx
├── components/
│   ├── dashboard/
│   │   ├── BalanceHeader.tsx
│   │   ├── QuickActions.tsx
│   │   ├── RecentActivity.tsx
│   │   └── StatusBar.tsx
│   └── transactions/
│       ├── SearchBar.tsx
│       ├── FilterTabs.tsx
│       ├── TransactionList.tsx
│       └── TransactionItem.tsx
├── store/
│   ├── dashboardStore.ts
│   └── transactionStore.ts
├── services/
│   ├── breezSdk.ts
│   ├── transactionCache.ts
│   └── eventBus.ts
├── database/
│   └── init.ts
├── utils/
│   └── formatters.ts
├── navigation/
│   └── DashboardNavigator.tsx
└── constants/
    └── transactions.ts

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is in early stages with only documentation (SRS and BRS) available. The SRS provides detailed wireframes, functional requirements (FR-UI-001, FR-HIST-001, FR-HIST-002), data models, and acceptance criteria. The app is a Lightning-only wallet using Breez SDK Spark for nodeless Lightning operations. Key dependencies include Breez SDK for transaction history (`listPayments`) and node state (`getInfo`), SQLite for local caching, and Expo/React Native for the UI framework. The dashboard must load within 1 second and display real-time Lightning balance, liquidity metrics, and recent transactions.

## Approach

The implementation follows a layered architecture: (1) Data layer with Breez SDK integration and SQLite caching, (2) State management for real-time updates, (3) UI components for Dashboard and Transaction History screens. The Dashboard will fetch node state from Breez SDK to display balance, liquidity, and connection status, while recent transactions come from cached SQLite data. The Transaction History screen implements filtering, search, and pagination with infinite scroll. Both screens leverage Breez SDK events for real-time updates and maintain local SQLite cache for performance, ensuring the dashboard loads under 1 second as required.

## Implementation Steps

### 1. Data Layer Setup

#### 1.1 SQLite Database Configuration
- Install and configure `expo-sqlite` or `react-native-sqlite-storage` for local database management
- Create database initialization module at `file:src/database/init.ts`
- Implement the transactions table schema as defined in file:docs/SRS.md (lines 2568-2590):
  - Fields: id, type, status, amount_sats, fee_sats, description, timestamp, confirmations, txid, payment_hash, preimage, invoice, destination_address
  - Indexes on timestamp (DESC), type, and status for query performance
- Implement the channels table schema (lines 2592-2609)
- Add database encryption using SQLCipher for security compliance
- Create database migration system for future schema updates

#### 1.2 Breez SDK Integration Service
- Create Breez SDK service module at `file:src/services/breezSdk.ts`
- Implement `getNodeState()` method wrapping Breez SDK's `getInfo()` to retrieve:
  - Lightning balance (local balance in channels)
  - Inbound liquidity (capacity to receive)
  - Outbound liquidity (capacity to send)
  - Connected peers count
  - Sync status
- Implement `fetchTransactionHistory()` method using Breez SDK's `listPayments()` with pagination support
- Add event listener registration for real-time updates:
  - `paymentReceived` - update balance and transaction list
  - `paymentSent` - update balance and transaction list
  - `nodeStateChanged` - refresh dashboard metrics
  - `syncComplete` - update sync status
- Implement error handling with retry logic for SDK operations

#### 1.3 Transaction Cache Manager
- Create cache manager at `file:src/services/transactionCache.ts`
- Implement `syncTransactionsToCache()` to fetch from Breez SDK and store in SQLite
- Add `getCachedTransactions()` with filtering and pagination:
  - Support filters: type (lightning_send, lightning_receive, withdrawal, all)
  - Support search by description or amount
  - Implement pagination with 50 items per page
  - Sort by timestamp descending
- Implement `getRecentTransactions(limit: number)` for dashboard (last 5)
- Add cache invalidation strategy triggered by SDK events
- Implement background sync to keep cache updated

### 2. State Management

#### 2.1 Dashboard State
- Create dashboard state store at `file:src/store/dashboardStore.ts` (using Zustand, Redux, or Context API based on project conventions)
- Define state shape:
  - `lightningBalance: number`
  - `inboundLiquidity: number`
  - `outboundLiquidity: number`
  - `channelCount: number`
  - `connectionStatus: 'connected' | 'disconnected' | 'syncing'`
  - `recentTransactions: Transaction[]`
  - `isLoading: boolean`
  - `lastUpdated: number`
- Implement actions:
  - `loadDashboardData()` - fetch from cache and SDK
  - `refreshBalance()` - update balance from SDK
  - `updateFromEvent(event)` - handle SDK events
- Add memoized selectors for derived data

#### 2.2 Transaction History State
- Create transaction history store at `file:src/store/transactionStore.ts`
- Define state shape:
  - `transactions: Transaction[]`
  - `filters: { type: string, search: string }`
  - `pagination: { page: number, hasMore: boolean }`
  - `isLoading: boolean`
  - `selectedTransaction: Transaction | null`
- Implement actions:
  - `loadTransactions(filters, page)` - fetch from cache
  - `searchTransactions(query)` - filter by description/amount
  - `filterByType(type)` - filter by transaction type
  - `loadMore()` - pagination support
  - `selectTransaction(id)` - for details view
  - `refreshTransactions()` - sync from SDK

### 3. Dashboard Screen Implementation

#### 3.1 Dashboard Component Structure
- Create main dashboard screen at `file:src/screens/DashboardScreen.tsx`
- Follow wireframe layout from file:docs/SRS.md (lines 910-1024)
- Component hierarchy:
  - `DashboardScreen` (container)
    - `BalanceHeader` - displays Lightning balance with network badge
    - `QuickActions` - Send, Receive, Withdraw, Scan buttons
    - `RecentActivity` - last 5 transactions
    - `StatusBar` - inbound/outbound liquidity, channel count

#### 3.2 Balance Header Component
- Create `file:src/components/dashboard/BalanceHeader.tsx`
- Display total Lightning balance from `dashboardStore.lightningBalance`
- Show network badge (Testnet/Mainnet) from wallet settings
- Implement unit conversion (sats ↔ BTC) based on user preference
- Add optional fiat conversion display (≈ $XXX USD) using cached exchange rates
- Apply gradient background styling as per wireframe
- Ensure text is accessible with proper contrast ratios

#### 3.3 Quick Actions Component
- Create `file:src/components/dashboard/QuickActions.tsx`
- Implement 4 action buttons in flex layout:
  - **Send** - navigate to Send Payment screen
  - **Receive** - navigate to Receive Payment screen
  - **Withdraw** - navigate to Withdrawal screen
  - **Scan** - open QR scanner with auto-detection
- Use icon library (e.g., react-native-vector-icons) for consistent icons
- Add haptic feedback on button press
- Implement navigation using React Navigation

#### 3.4 Recent Activity Component
- Create `file:src/components/dashboard/RecentActivity.tsx`
- Display last 5 transactions from `dashboardStore.recentTransactions`
- Each transaction item shows:
  - Icon based on type (⚡ Lightning, 🔗 Withdrawal)
  - Description text
  - Relative timestamp (e.g., "2 hours ago")
  - Amount with +/- indicator and color coding
- Add "See All" link navigating to Transaction History screen
- Implement empty state when no transactions exist
- Use FlatList for rendering with keyExtractor

#### 3.5 Status Bar Component
- Create `file:src/components/dashboard/StatusBar.tsx`
- Display 3 metrics in equal-width columns:
  - **Inbound**: `dashboardStore.inboundLiquidity` formatted in sats
  - **Outbound**: `dashboardStore.outboundLiquidity` formatted in sats
  - **Channels**: `dashboardStore.channelCount` with "active" label
- Apply background color and border styling per wireframe
- Update in real-time when node state changes

#### 3.6 Dashboard Data Loading
- Implement `useEffect` hook in DashboardScreen to load data on mount
- Call `dashboardStore.loadDashboardData()` which:
  1. Loads recent transactions from SQLite cache (fast)
  2. Fetches node state from Breez SDK
  3. Updates state with combined data
- Implement pull-to-refresh functionality using RefreshControl
- Add loading skeleton/shimmer while data loads
- Ensure total load time is under 1 second (AC-UI-001-05)
- Subscribe to Breez SDK events for real-time updates

### 4. Transaction History Screen Implementation

#### 4.1 Transaction List Component
- Create main screen at `file:src/screens/TransactionHistoryScreen.tsx`
- Follow wireframe layout from file:docs/SRS.md (lines 1370-1501)
- Component hierarchy:
  - `TransactionHistoryScreen` (container)
    - `SearchBar` - search input with icon
    - `FilterTabs` - All, Lightning, Withdrawals, Pending
    - `TransactionList` - grouped by date with infinite scroll

#### 4.2 Search and Filter Bar
- Create `file:src/components/transactions/SearchBar.tsx`
- Implement search input with debounced onChange (300ms delay)
- Call `transactionStore.searchTransactions(query)` on input change
- Search matches against transaction description and amount
- Add clear button (X) to reset search
- Create `file:src/components/transactions/FilterTabs.tsx`
- Implement horizontal scrollable tabs: All, ⚡ Lightning, 🔗 Withdrawals, ⏳ Pending
- Highlight active filter with background color change
- Call `transactionStore.filterByType(type)` on tab press

#### 4.3 Transaction List with Grouping
- Create `file:src/components/transactions/TransactionList.tsx`
- Group transactions by date (Today, Yesterday, specific dates)
- Use SectionList for grouped rendering with date headers
- Implement infinite scroll using `onEndReached` callback:
  - Trigger `transactionStore.loadMore()` when reaching bottom
  - Load next 50 transactions from cache
  - Show loading indicator at bottom while fetching
- Each transaction item component (`TransactionItem.tsx`):
  - Icon with background color based on type (lightning/onchain/pending)
  - Description and metadata (time, type, confirmations)
  - Amount with color coding (green for positive, black for negative)
  - Status badge (Confirmed/Pending)
- Add pull-to-refresh to sync from Breez SDK
- Implement empty state when no transactions match filters

#### 4.4 Transaction Details Screen
- Create `file:src/screens/TransactionDetailsScreen.tsx`
- Display different fields based on transaction type:
  - **Withdrawal** (AC-HIST-002-01):
    - Destination address (external Layer 1 address)
    - Amount in sats
    - On-chain fee
    - Confirmations count
    - Transaction ID (txid)
  - **Lightning** (AC-HIST-002-02):
    - Invoice (Bolt11 string)
    - Amount in sats
    - Routing fee
    - Payment preimage (if available)
    - Description
    - Payment hash
- Implement copy functionality for each field:
  - Use Clipboard API from React Native
  - Show toast notification on successful copy
- Add share button to share transaction details as text
- For withdrawals, add "View on Explorer" button:
  - Link to mempool.space with txid
  - Open in external browser or in-app WebView
- Style with card layout and proper spacing

### 5. Utility Functions and Helpers

#### 5.1 Formatting Utilities
- Create `file:src/utils/formatters.ts`
- Implement `formatSats(amount: number, unit: 'sats' | 'BTC')`:
  - Format with thousands separators
  - Handle BTC conversion (1 BTC = 100,000,000 sats)
  - Return formatted string
- Implement `formatTimestamp(timestamp: number)`:
  - Return relative time for recent transactions ("2 hours ago", "Yesterday")
  - Return formatted date for older transactions ("Feb 4, 2026")
- Implement `formatAddress(address: string, truncate: boolean)`:
  - Truncate long addresses for display (bc1q...xyz)
  - Return full address when needed
- Add `formatTransactionType(type: string)` for display labels

#### 5.2 Navigation Helpers
- Create `file:src/navigation/DashboardNavigator.tsx`
- Configure stack navigator with screens:
  - Dashboard (initial route)
  - Send Payment
  - Receive Payment
  - Withdraw
  - Transaction History
  - Transaction Details
- Set up navigation params typing for type safety
- Configure header styles consistent with wireframes

#### 5.3 Constants and Configuration
- Create `file:src/constants/transactions.ts`
- Define transaction type enums matching data model
- Define status enums (pending, confirmed, failed)
- Set pagination constants (PAGE_SIZE = 50)
- Define block explorer URLs (testnet/mainnet)

### 6. Performance Optimizations

#### 6.1 Dashboard Performance
- Implement React.memo for all dashboard components to prevent unnecessary re-renders
- Use useMemo for expensive calculations (balance conversions, date formatting)
- Implement virtualization for recent transactions list (though only 5 items)
- Cache node state in memory with TTL (time-to-live) of 5 seconds
- Prefetch recent transactions on app launch in background
- Use skeleton loaders instead of spinners for better perceived performance

#### 6.2 Transaction List Performance
- Use FlatList/SectionList with proper optimization props:
  - `windowSize={10}` - render 10 screens worth of content
  - `maxToRenderPerBatch={10}` - render 10 items per batch
  - `updateCellsBatchingPeriod={50}` - batch updates every 50ms
  - `removeClippedSubviews={true}` - unmount off-screen items
- Implement `getItemLayout` for consistent item heights (skip measurement)
- Use `keyExtractor` with stable IDs (transaction.id)
- Memoize transaction item components
- Implement database query optimization with proper indexes
- Add request debouncing for search (300ms)

#### 6.3 Caching Strategy
- Implement two-tier caching:
  - **Memory cache**: Recent transactions and node state (fast access)
  - **SQLite cache**: Full transaction history (persistent)
- Set cache invalidation rules:
  - Invalidate on SDK payment events
  - Refresh every 30 seconds in background
  - Force refresh on pull-to-refresh
- Implement optimistic updates for better UX:
  - Update UI immediately on user action
  - Sync with SDK in background
  - Rollback on failure

### 7. Real-time Updates

#### 7.1 SDK Event Listeners
- Register event listeners in `file:src/services/breezSdk.ts`
- Handle `paymentReceived` event:
  - Add new transaction to cache
  - Update dashboard balance
  - Show notification to user
  - Refresh transaction list if visible
- Handle `paymentSent` event:
  - Update transaction status in cache
  - Update dashboard balance
  - Refresh transaction list
- Handle `nodeStateChanged` event:
  - Update balance, liquidity, channel count
  - Refresh dashboard metrics
- Implement event queue to batch rapid updates

#### 7.2 State Synchronization
- Use event emitter pattern to propagate SDK events to UI
- Implement global event bus at `file:src/services/eventBus.ts`
- Subscribe to events in dashboard and transaction screens
- Debounce rapid updates to prevent UI thrashing
- Ensure state consistency between cache and SDK

### 8. Error Handling and Edge Cases

#### 8.1 Error Handling
- Implement error boundary component for crash recovery
- Add try-catch blocks around all SDK calls
- Display user-friendly error messages for common failures:
  - Network disconnection
  - SDK initialization failure
  - Database errors
- Implement retry logic with exponential backoff for transient errors
- Log errors to analytics service for monitoring

#### 8.2 Edge Cases
- Handle empty states:
  - No transactions yet (show onboarding message)
  - No search results (show "No results found")
  - No network connection (show offline indicator)
- Handle pending transactions:
  - Show pending status badge
  - Update when confirmed via SDK event
  - Handle failed transactions
- Handle large transaction lists:
  - Implement pagination to avoid memory issues
  - Lazy load transaction details
- Handle concurrent updates:
  - Use database transactions for atomic updates
  - Implement optimistic locking if needed

### 9. Testing Considerations

#### 9.1 Component Testing
- Test dashboard components render correctly with mock data
- Test transaction list filtering and search functionality
- Test pagination and infinite scroll behavior
- Test pull-to-refresh functionality
- Verify navigation between screens

#### 9.2 Integration Testing
- Test Breez SDK integration with mock SDK responses
- Test SQLite cache operations (CRUD)
- Test event listener registration and handling
- Test state synchronization between cache and SDK
- Verify performance meets 1-second load time requirement

#### 9.3 Data Testing
- Test transaction data model validation
- Test database migrations
- Test cache invalidation logic
- Test data formatting utilities
- Verify data persistence across app restarts

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Dashboard
    participant Store
    participant Cache
    participant BreezSDK
    
    User->>Dashboard: Open App
    Dashboard->>Store: loadDashboardData()
    Store->>Cache: getCachedTransactions(5)
    Cache-->>Store: Recent 5 transactions
    Store->>BreezSDK: getInfo()
    BreezSDK-->>Store: Node state (balance, liquidity)
    Store-->>Dashboard: Update UI
    Dashboard-->>User: Display (< 1s)
    
    BreezSDK->>Store: paymentReceived event
    Store->>Cache: syncTransactionsToCache()
    Store-->>Dashboard: Update balance & transactions
    Dashboard-->>User: Real-time update
    
    User->>Dashboard: Tap "See All"
    Dashboard->>User: Navigate to Transaction History
    User->>Store: Filter by Lightning
    Store->>Cache: getCachedTransactions(filter, page)
    Cache-->>Store: Filtered transactions
    Store-->>User: Display filtered list
    
    User->>Store: Scroll to bottom
    Store->>Cache: getCachedTransactions(page+1)
    Cache-->>Store: Next 50 transactions
    Store-->>User: Append to list
```

## Component Structure

```
src/
├── screens/
│   ├── DashboardScreen.tsx
│   ├── TransactionHistoryScreen.tsx
│   └── TransactionDetailsScreen.tsx
├── components/
│   ├── dashboard/
│   │   ├── BalanceHeader.tsx
│   │   ├── QuickActions.tsx
│   │   ├── RecentActivity.tsx
│   │   └── StatusBar.tsx
│   └── transactions/
│       ├── SearchBar.tsx
│       ├── FilterTabs.tsx
│       ├── TransactionList.tsx
│       └── TransactionItem.tsx
├── store/
│   ├── dashboardStore.ts
│   └── transactionStore.ts
├── services/
│   ├── breezSdk.ts
│   ├── transactionCache.ts
│   └── eventBus.ts
├── database/
│   └── init.ts
├── utils/
│   └── formatters.ts
├── navigation/
│   └── DashboardNavigator.tsx
└── constants/
    └── transactions.ts
```

---

Execution Information

Branch: main
Commit: 342104b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The codebase is in early stages with only documentation (SRS and BRS) available. The SRS provides detailed wireframes, functional requirements (FR-UI-001, FR-HIST-001, FR-HIST-002), data models, and acceptance criteria. The app is a Lightning-only wallet using Breez SDK Spark for nodeless Lightning operations. Key dependencies include Breez SDK for transaction history (listPayments) and node state (getInfo), SQLite for local caching, and Expo/React Native for the UI framework. The dashboard must load within 1 second and display real-time Lightning balance, liquidity metrics, and recent transactions.

Approach

The implementation follows a layered architecture: (1) Data layer with Breez SDK integration and SQLite caching, (2) State management for real-time updates, (3) UI components for Dashboard and Transaction History screens. The Dashboard will fetch node state from Breez SDK to display balance, liquidity, and connection status, while recent transactions come from cached SQLite data. The Transaction History screen implements filtering, search, and pagination with infinite scroll. Both screens leverage Breez SDK events for real-time updates and maintain local SQLite cache for performance, ensuring the dashboard loads under 1 second as required.

Implementation Steps

1. Data Layer Setup

1.1 SQLite Database Configuration

• Install and configure expo-sqlite or react-native-sqlite-storage for local database management
• Create database initialization module at file:src/database/init.ts
• Implement the transactions table schema as defined in file:docs/SRS.md (lines 2568-2590):
  • Fields: id, type, status, amount_sats, fee_sats, description, timestamp, confirmations, txid, payment_hash, preimage, invoice, destination_address
  • Indexes on timestamp (DESC), type, and status for query performance
• Implement the channels table schema (lines 2592-2609)
• Add database encryption using SQLCipher for security compliance
• Create database migration system for future schema updates

1.2 Breez SDK Integration Service

• Create Breez SDK service module at file:src/services/breezSdk.ts
• Implement getNodeState() method wrapping Breez SDK's getInfo() to retrieve:
  • Lightning balance (local balance in channels)
  • Inbound liquidity (capacity to receive)
  • Outbound liquidity (capacity to send)
  • Connected peers count
  • Sync status
• Implement fetchTransactionHistory() method using Breez SDK's listPayments() with pagination support
• Add event listener registration for real-time updates:
  • paymentReceived - update balance and transaction list
  • paymentSent - update balance and transaction list
  • nodeStateChanged - refresh dashboard metrics
  • syncComplete - update sync status
• Implement error handling with retry logic for SDK operations

1.3 Transaction Cache Manager

• Create cache manager at file:src/services/transactionCache.ts
• Implement syncTransactionsToCache() to fetch from Breez SDK and store in SQLite
• Add getCachedTransactions() with filtering and pagination:
  • Support filters: type (lightning_send, lightning_receive, withdrawal, all)
  • Support search by description or amount
  • Implement pagination with 50 items per page
  • Sort by timestamp descending
• Implement getRecentTransactions(limit: number) for dashboard (last 5)
• Add cache invalidation strategy triggered by SDK events
• Implement background sync to keep cache updated

2. State Management

2.1 Dashboard State

• Create dashboard state store at file:src/store/dashboardStore.ts (using Zustand, Redux, or Context API based on project conventions)
• Define state shape:
  • lightningBalance: number
  • inboundLiquidity: number
  • outboundLiquidity: number
  • channelCount: number
  • connectionStatus: 'connected' | 'disconnected' | 'syncing'
  • recentTransactions: Transaction[]
  • isLoading: boolean
  • lastUpdated: number
• Implement actions:
  • loadDashboardData() - fetch from cache and SDK
  • refreshBalance() - update balance from SDK
  • updateFromEvent(event) - handle SDK events
• Add memoized selectors for derived data

2.2 Transaction History State

• Create transaction history store at file:src/store/transactionStore.ts
• Define state shape:
  • transactions: Transaction[]
  • filters: { type: string, search: string }
  • pagination: { page: number, hasMore: boolean }
  • isLoading: boolean
  • selectedTransaction: Transaction | null
• Implement actions:
  • loadTransactions(filters, page) - fetch from cache
  • searchTransactions(query) - filter by description/amount
  • filterByType(type) - filter by transaction type
  • loadMore() - pagination support
  • selectTransaction(id) - for details view
  • refreshTransactions() - sync from SDK

3. Dashboard Screen Implementation

3.1 Dashboard Component Structure

• Create main dashboard screen at file:src/screens/DashboardScreen.tsx
• Follow wireframe layout from file:docs/SRS.md (lines 910-1024)
• Component hierarchy:
  • DashboardScreen (container)
    • BalanceHeader - displays Lightning balance with network badge
    • QuickActions - Send, Receive, Withdraw, Scan buttons
    • RecentActivity - last 5 transactions
    • StatusBar - inbound/outbound liquidity, channel count

3.2 Balance Header Component

• Create file:src/components/dashboard/BalanceHeader.tsx
• Display total Lightning balance from dashboardStore.lightningBalance
• Show network badge (Testnet/Mainnet) from wallet settings
• Implement unit conversion (sats ↔ BTC) based on user preference
• Add optional fiat conversion display (≈ $XXX USD) using cached exchange rates
• Apply gradient background styling as per wireframe
• Ensure text is accessible with proper contrast ratios

3.3 Quick Actions Component

• Create file:src/components/dashboard/QuickActions.tsx
• Implement 4 action buttons in flex layout:
  • Send - navigate to Send Payment screen
  • Receive - navigate to Receive Payment screen
  • Withdraw - navigate to Withdrawal screen
  • Scan - open QR scanner with auto-detection
• Use icon library (e.g., react-native-vector-icons) for consistent icons
• Add haptic feedback on button press
• Implement navigation using React Navigation

3.4 Recent Activity Component

• Create file:src/components/dashboard/RecentActivity.tsx
• Display last 5 transactions from dashboardStore.recentTransactions
• Each transaction item shows:
  • Icon based on type (⚡ Lightning, 🔗 Withdrawal)
  • Description text
  • Relative timestamp (e.g., "2 hours ago")
  • Amount with +/- indicator and color coding
• Add "See All" link navigating to Transaction History screen
• Implement empty state when no transactions exist
• Use FlatList for rendering with keyExtractor

3.5 Status Bar Component

• Create file:src/components/dashboard/StatusBar.tsx
• Display 3 metrics in equal-width columns:
  • Inbound: dashboardStore.inboundLiquidity formatted in sats
  • Outbound: dashboardStore.outboundLiquidity formatted in sats
  • Channels: dashboardStore.channelCount with "active" label
• Apply background color and border styling per wireframe
• Update in real-time when node state changes

3.6 Dashboard Data Loading

• Implement useEffect hook in DashboardScreen to load data on mount
• Call dashboardStore.loadDashboardData() which:
  1. Loads recent transactions from SQLite cache (fast)
  2. Fetches node state from Breez SDK
  3. Updates state with combined data
• Implement pull-to-refresh functionality using RefreshControl
• Add loading skeleton/shimmer while data loads
• Ensure total load time is under 1 second (AC-UI-001-05)
• Subscribe to Breez SDK events for real-time updates

4. Transaction History Screen Implementation

4.1 Transaction List Component

• Create main screen at file:src/screens/TransactionHistoryScreen.tsx
• Follow wireframe layout from file:docs/SRS.md (lines 1370-1501)
• Component hierarchy:
  • TransactionHistoryScreen (container)
    • SearchBar - search input with icon
    • FilterTabs - All, Lightning, Withdrawals, Pending
    • TransactionList - grouped by date with infinite scroll

4.2 Search and Filter Bar

• Create file:src/components/transactions/SearchBar.tsx
• Implement search input with debounced onChange (300ms delay)
• Call transactionStore.searchTransactions(query) on input change
• Search matches against transaction description and amount
• Add clear button (X) to reset search
• Create file:src/components/transactions/FilterTabs.tsx
• Implement horizontal scrollable tabs: All, ⚡ Lightning, 🔗 Withdrawals, ⏳ Pending
• Highlight active filter with background color change
• Call transactionStore.filterByType(type) on tab press

4.3 Transaction List with Grouping

• Create file:src/components/transactions/TransactionList.tsx
• Group transactions by date (Today, Yesterday, specific dates)
• Use SectionList for grouped rendering with date headers
• Implement infinite scroll using onEndReached callback:
  • Trigger transactionStore.loadMore() when reaching bottom
  • Load next 50 transactions from cache
  • Show loading indicator at bottom while fetching
• Each transaction item component (TransactionItem.tsx):
  • Icon with background color based on type (lightning/onchain/pending)
  • Description and metadata (time, type, confirmations)
  • Amount with color coding (green for positive, black for negative)
  • Status badge (Confirmed/Pending)
• Add pull-to-refresh to sync from Breez SDK
• Implement empty state when no transactions match filters

4.4 Transaction Details Screen

• Create file:src/screens/TransactionDetailsScreen.tsx
• Display different fields based on transaction type:
  • Withdrawal (AC-HIST-002-01):
    • Destination address (external Layer 1 address)
    • Amount in sats
    • On-chain fee
    • Confirmations count
    • Transaction ID (txid)
  • Lightning (AC-HIST-002-02):
    • Invoice (Bolt11 string)
    • Amount in sats
    • Routing fee
    • Payment preimage (if available)
    • Description
    • Payment hash
• Implement copy functionality for each field:
  • Use Clipboard API from React Native
  • Show toast notification on successful copy
• Add share button to share transaction details as text
• For withdrawals, add "View on Explorer" button:
  • Link to mempool.space with txid
  • Open in external browser or in-app WebView
• Style with card layout and proper spacing

5. Utility Functions and Helpers

5.1 Formatting Utilities

• Create file:src/utils/formatters.ts
• Implement formatSats(amount: number, unit: 'sats' | 'BTC'):
  • Format with thousands separators
  • Handle BTC conversion (1 BTC = 100,000,000 sats)
  • Return formatted string
• Implement formatTimestamp(timestamp: number):
  • Return relative time for recent transactions ("2 hours ago", "Yesterday")
  • Return formatted date for older transactions ("Feb 4, 2026")
• Implement formatAddress(address: string, truncate: boolean):
  • Truncate long addresses for display (bc1q...xyz)
  • Return full address when needed
• Add formatTransactionType(type: string) for display labels

5.2 Navigation Helpers

• Create file:src/navigation/DashboardNavigator.tsx
• Configure stack navigator with screens:
  • Dashboard (initial route)
  • Send Payment
  • Receive Payment
  • Withdraw
  • Transaction History
  • Transaction Details
• Set up navigation params typing for type safety
• Configure header styles consistent with wireframes

5.3 Constants and Configuration

• Create file:src/constants/transactions.ts
• Define transaction type enums matching data model
• Define status enums (pending, confirmed, failed)
• Set pagination constants (PAGE_SIZE = 50)
• Define block explorer URLs (testnet/mainnet)

6. Performance Optimizations

6.1 Dashboard Performance

• Implement React.memo for all dashboard components to prevent unnecessary re-renders
• Use useMemo for expensive calculations (balance conversions, date formatting)
• Implement virtualization for recent transactions list (though only 5 items)
• Cache node state in memory with TTL (time-to-live) of 5 seconds
• Prefetch recent transactions on app launch in background
• Use skeleton loaders instead of spinners for better perceived performance

6.2 Transaction List Performance

• Use FlatList/SectionList with proper optimization props:
  • windowSize={10} - render 10 screens worth of content
  • maxToRenderPerBatch={10} - render 10 items per batch
  • updateCellsBatchingPeriod={50} - batch updates every 50ms
  • removeClippedSubviews={true} - unmount off-screen items
• Implement getItemLayout for consistent item heights (skip measurement)
• Use keyExtractor with stable IDs (transaction.id)
• Memoize transaction item components
• Implement database query optimization with proper indexes
• Add request debouncing for search (300ms)

6.3 Caching Strategy

• Implement two-tier caching:
  • Memory cache: Recent transactions and node state (fast access)
  • SQLite cache: Full transaction history (persistent)
• Set cache invalidation rules:
  • Invalidate on SDK payment events
  • Refresh every 30 seconds in background
  • Force refresh on pull-to-refresh
• Implement optimistic updates for better UX:
  • Update UI immediately on user action
  • Sync with SDK in background
  • Rollback on failure

7. Real-time Updates

7.1 SDK Event Listeners

• Register event listeners in file:src/services/breezSdk.ts
• Handle paymentReceived event:
  • Add new transaction to cache
  • Update dashboard balance
  • Show notification to user
  • Refresh transaction list if visible
• Handle paymentSent event:
  • Update transaction status in cache
  • Update dashboard balance
  • Refresh transaction list
• Handle nodeStateChanged event:
  • Update balance, liquidity, channel count
  • Refresh dashboard metrics
• Implement event queue to batch rapid updates

7.2 State Synchronization

• Use event emitter pattern to propagate SDK events to UI
• Implement global event bus at file:src/services/eventBus.ts
• Subscribe to events in dashboard and transaction screens
• Debounce rapid updates to prevent UI thrashing
• Ensure state consistency between cache and SDK

8. Error Handling and Edge Cases

8.1 Error Handling

• Implement error boundary component for crash recovery
• Add try-catch blocks around all SDK calls
• Display user-friendly error messages for common failures:
  • Network disconnection
  • SDK initialization failure
  • Database errors
• Implement retry logic with exponential backoff for transient errors
• Log errors to analytics service for monitoring

8.2 Edge Cases

• Handle empty states:
  • No transactions yet (show onboarding message)
  • No search results (show "No results found")
  • No network connection (show offline indicator)
• Handle pending transactions:
  • Show pending status badge
  • Update when confirmed via SDK event
  • Handle failed transactions
• Handle large transaction lists:
  • Implement pagination to avoid memory issues
  • Lazy load transaction details
• Handle concurrent updates:
  • Use database transactions for atomic updates
  • Implement optimistic locking if needed

9. Testing Considerations

9.1 Component Testing

• Test dashboard components render correctly with mock data
• Test transaction list filtering and search functionality
• Test pagination and infinite scroll behavior
• Test pull-to-refresh functionality
• Verify navigation between screens

9.2 Integration Testing

• Test Breez SDK integration with mock SDK responses
• Test SQLite cache operations (CRUD)
• Test event listener registration and handling
• Test state synchronization between cache and SDK
• Verify performance meets 1-second load time requirement

9.3 Data Testing

• Test transaction data model validation
• Test database migrations
• Test cache invalidation logic
• Test data formatting utilities
• Verify data persistence across app restarts

Architecture Diagram

sequenceDiagram
    participant User
    participant Dashboard
    participant Store
    participant Cache
    participant BreezSDK
    
    User->>Dashboard: Open App
    Dashboard->>Store: loadDashboardData()
    Store->>Cache: getCachedTransactions(5)
    Cache-->>Store: Recent 5 transactions
    Store->>BreezSDK: getInfo()
    BreezSDK-->>Store: Node state (balance, liquidity)
    Store-->>Dashboard: Update UI
    Dashboard-->>User: Display (< 1s)
    
    BreezSDK->>Store: paymentReceived event
    Store->>Cache: syncTransactionsToCache()
    Store-->>Dashboard: Update balance & transactions
    Dashboard-->>User: Real-time update
    
    User->>Dashboard: Tap "See All"
    Dashboard->>User: Navigate to Transaction History
    User->>Store: Filter by Lightning
    Store->>Cache: getCachedTransactions(filter, page)
    Cache-->>Store: Filtered transactions
    Store-->>User: Display filtered list
    
    User->>Store: Scroll to bottom
    Store->>Cache: getCachedTransactions(page+1)
    Cache-->>Store: Next 50 transactions
    Store-->>User: Append to list

Loading

Component Structure

src/
├── screens/
│   ├── DashboardScreen.tsx
│   ├── TransactionHistoryScreen.tsx
│   └── TransactionDetailsScreen.tsx
├── components/
│   ├── dashboard/
│   │   ├── BalanceHeader.tsx
│   │   ├── QuickActions.tsx
│   │   ├── RecentActivity.tsx
│   │   └── StatusBar.tsx
│   └── transactions/
│       ├── SearchBar.tsx
│       ├── FilterTabs.tsx
│       ├── TransactionList.tsx
│       └── TransactionItem.tsx
├── store/
│   ├── dashboardStore.ts
│   └── transactionStore.ts
├── services/
│   ├── breezSdk.ts
│   ├── transactionCache.ts
│   └── eventBus.ts
├── database/
│   └── init.ts
├── utils/
│   └── formatters.ts
├── navigation/
│   └── DashboardNavigator.tsx
└── constants/
    └── transactions.ts

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is in early stages with only documentation (SRS and BRS) available. The SRS provides detailed wireframes, functional requirements (FR-UI-001, FR-HIST-001, FR-HIST-002), data models, and acceptance criteria. The app is a Lightning-only wallet using Breez SDK Spark for nodeless Lightning operations. Key dependencies include Breez SDK for transaction history (`listPayments`) and node state (`getInfo`), SQLite for local caching, and Expo/React Native for the UI framework. The dashboard must load within 1 second and display real-time Lightning balance, liquidity metrics, and recent transactions.

## Approach

The implementation follows a layered architecture: (1) Data layer with Breez SDK integration and SQLite caching, (2) State management for real-time updates, (3) UI components for Dashboard and Transaction History screens. The Dashboard will fetch node state from Breez SDK to display balance, liquidity, and connection status, while recent transactions come from cached SQLite data. The Transaction History screen implements filtering, search, and pagination with infinite scroll. Both screens leverage Breez SDK events for real-time updates and maintain local SQLite cache for performance, ensuring the dashboard loads under 1 second as required.

## Implementation Steps

### 1. Data Layer Setup

#### 1.1 SQLite Database Configuration
- Install and configure `expo-sqlite` or `react-native-sqlite-storage` for local database management
- Create database initialization module at `file:src/database/init.ts`
- Implement the transactions table schema as defined in file:docs/SRS.md (lines 2568-2590):
  - Fields: id, type, status, amount_sats, fee_sats, description, timestamp, confirmations, txid, payment_hash, preimage, invoice, destination_address
  - Indexes on timestamp (DESC), type, and status for query performance
- Implement the channels table schema (lines 2592-2609)
- Add database encryption using SQLCipher for security compliance
- Create database migration system for future schema updates

#### 1.2 Breez SDK Integration Service
- Create Breez SDK service module at `file:src/services/breezSdk.ts`
- Implement `getNodeState()` method wrapping Breez SDK's `getInfo()` to retrieve:
  - Lightning balance (local balance in channels)
  - Inbound liquidity (capacity to receive)
  - Outbound liquidity (capacity to send)
  - Connected peers count
  - Sync status
- Implement `fetchTransactionHistory()` method using Breez SDK's `listPayments()` with pagination support
- Add event listener registration for real-time updates:
  - `paymentReceived` - update balance and transaction list
  - `paymentSent` - update balance and transaction list
  - `nodeStateChanged` - refresh dashboard metrics
  - `syncComplete` - update sync status
- Implement error handling with retry logic for SDK operations

#### 1.3 Transaction Cache Manager
- Create cache manager at `file:src/services/transactionCache.ts`
- Implement `syncTransactionsToCache()` to fetch from Breez SDK and store in SQLite
- Add `getCachedTransactions()` with filtering and pagination:
  - Support filters: type (lightning_send, lightning_receive, withdrawal, all)
  - Support search by description or amount
  - Implement pagination with 50 items per page
  - Sort by timestamp descending
- Implement `getRecentTransactions(limit: number)` for dashboard (last 5)
- Add cache invalidation strategy triggered by SDK events
- Implement background sync to keep cache updated

### 2. State Management

#### 2.1 Dashboard State
- Create dashboard state store at `file:src/store/dashboardStore.ts` (using Zustand, Redux, or Context API based on project conventions)
- Define state shape:
  - `lightningBalance: number`
  - `inboundLiquidity: number`
  - `outboundLiquidity: number`
  - `channelCount: number`
  - `connectionStatus: 'connected' | 'disconnected' | 'syncing'`
  - `recentTransactions: Transaction[]`
  - `isLoading: boolean`
  - `lastUpdated: number`
- Implement actions:
  - `loadDashboardData()` - fetch from cache and SDK
  - `refreshBalance()` - update balance from SDK
  - `updateFromEvent(event)` - handle SDK events
- Add memoized selectors for derived data

#### 2.2 Transaction History State
- Create transaction history store at `file:src/store/transactionStore.ts`
- Define state shape:
  - `transactions: Transaction[]`
  - `filters: { type: string, search: string }`
  - `pagination: { page: number, hasMore: boolean }`
  - `isLoading: boolean`
  - `selectedTransaction: Transaction | null`
- Implement actions:
  - `loadTransactions(filters, page)` - fetch from cache
  - `searchTransactions(query)` - filter by description/amount
  - `filterByType(type)` - filter by transaction type
  - `loadMore()` - pagination support
  - `selectTransaction(id)` - for details view
  - `refreshTransactions()` - sync from SDK

### 3. Dashboard Screen Implementation

#### 3.1 Dashboard Component Structure
- Create main dashboard screen at `file:src/screens/DashboardScreen.tsx`
- Follow wireframe layout from file:docs/SRS.md (lines 910-1024)
- Component hierarchy:
  - `DashboardScreen` (container)
    - `BalanceHeader` - displays Lightning balance with network badge
    - `QuickActions` - Send, Receive, Withdraw, Scan buttons
    - `RecentActivity` - last 5 transactions
    - `StatusBar` - inbound/outbound liquidity, channel count

#### 3.2 Balance Header Component
- Create `file:src/components/dashboard/BalanceHeader.tsx`
- Display total Lightning balance from `dashboardStore.lightningBalance`
- Show network badge (Testnet/Mainnet) from wallet settings
- Implement unit conversion (sats ↔ BTC) based on user preference
- Add optional fiat conversion display (≈ $XXX USD) using cached exchange rates
- Apply gradient background styling as per wireframe
- Ensure text is accessible with proper contrast ratios

#### 3.3 Quick Actions Component
- Create `file:src/components/dashboard/QuickActions.tsx`
- Implement 4 action buttons in flex layout:
  - **Send** - navigate to Send Payment screen
  - **Receive** - navigate to Receive Payment screen
  - **Withdraw** - navigate to Withdrawal screen
  - **Scan** - open QR scanner with auto-detection
- Use icon library (e.g., react-native-vector-icons) for consistent icons
- Add haptic feedback on button press
- Implement navigation using React Navigation

#### 3.4 Recent Activity Component
- Create `file:src/components/dashboard/RecentActivity.tsx`
- Display last 5 transactions from `dashboardStore.recentTransactions`
- Each transaction item shows:
  - Icon based on type (⚡ Lightning, 🔗 Withdrawal)
  - Description text
  - Relative timestamp (e.g., "2 hours ago")
  - Amount with +/- indicator and color coding
- Add "See All" link navigating to Transaction History screen
- Implement empty state when no transactions exist
- Use FlatList for rendering with keyExtractor

#### 3.5 Status Bar Component
- Create `file:src/components/dashboard/StatusBar.tsx`
- Display 3 metrics in equal-width columns:
  - **Inbound**: `dashboardStore.inboundLiquidity` formatted in sats
  - **Outbound**: `dashboardStore.outboundLiquidity` formatted in sats
  - **Channels**: `dashboardStore.channelCount` with "active" label
- Apply background color and border styling per wireframe
- Update in real-time when node state changes

#### 3.6 Dashboard Data Loading
- Implement `useEffect` hook in DashboardScreen to load data on mount
- Call `dashboardStore.loadDashboardData()` which:
  1. Loads recent transactions from SQLite cache (fast)
  2. Fetches node state from Breez SDK
  3. Updates state with combined data
- Implement pull-to-refresh functionality using RefreshControl
- Add loading skeleton/shimmer while data loads
- Ensure total load time is under 1 second (AC-UI-001-05)
- Subscribe to Breez SDK events for real-time updates

### 4. Transaction History Screen Implementation

#### 4.1 Transaction List Component
- Create main screen at `file:src/screens/TransactionHistoryScreen.tsx`
- Follow wireframe layout from file:docs/SRS.md (lines 1370-1501)
- Component hierarchy:
  - `TransactionHistoryScreen` (container)
    - `SearchBar` - search input with icon
    - `FilterTabs` - All, Lightning, Withdrawals, Pending
    - `TransactionList` - grouped by date with infinite scroll

#### 4.2 Search and Filter Bar
- Create `file:src/components/transactions/SearchBar.tsx`
- Implement search input with debounced onChange (300ms delay)
- Call `transactionStore.searchTransactions(query)` on input change
- Search matches against transaction description and amount
- Add clear button (X) to reset search
- Create `file:src/components/transactions/FilterTabs.tsx`
- Implement horizontal scrollable tabs: All, ⚡ Lightning, 🔗 Withdrawals, ⏳ Pending
- Highlight active filter with background color change
- Call `transactionStore.filterByType(type)` on tab press

#### 4.3 Transaction List with Grouping
- Create `file:src/components/transactions/TransactionList.tsx`
- Group transactions by date (Today, Yesterday, specific dates)
- Use SectionList for grouped rendering with date headers
- Implement infinite scroll using `onEndReached` callback:
  - Trigger `transactionStore.loadMore()` when reaching bottom
  - Load next 50 transactions from cache
  - Show loading indicator at bottom while fetching
- Each transaction item component (`TransactionItem.tsx`):
  - Icon with background color based on type (lightning/onchain/pending)
  - Description and metadata (time, type, confirmations)
  - Amount with color coding (green for positive, black for negative)
  - Status badge (Confirmed/Pending)
- Add pull-to-refresh to sync from Breez SDK
- Implement empty state when no transactions match filters

#### 4.4 Transaction Details Screen
- Create `file:src/screens/TransactionDetailsScreen.tsx`
- Display different fields based on transaction type:
  - **Withdrawal** (AC-HIST-002-01):
    - Destination address (external Layer 1 address)
    - Amount in sats
    - On-chain fee
    - Confirmations count
    - Transaction ID (txid)
  - **Lightning** (AC-HIST-002-02):
    - Invoice (Bolt11 string)
    - Amount in sats
    - Routing fee
    - Payment preimage (if available)
    - Description
    - Payment hash
- Implement copy functionality for each field:
  - Use Clipboard API from React Native
  - Show toast notification on successful copy
- Add share button to share transaction details as text
- For withdrawals, add "View on Explorer" button:
  - Link to mempool.space with txid
  - Open in external browser or in-app WebView
- Style with card layout and proper spacing

### 5. Utility Functions and Helpers

#### 5.1 Formatting Utilities
- Create `file:src/utils/formatters.ts`
- Implement `formatSats(amount: number, unit: 'sats' | 'BTC')`:
  - Format with thousands separators
  - Handle BTC conversion (1 BTC = 100,000,000 sats)
  - Return formatted string
- Implement `formatTimestamp(timestamp: number)`:
  - Return relative time for recent transactions ("2 hours ago", "Yesterday")
  - Return formatted date for older transactions ("Feb 4, 2026")
- Implement `formatAddress(address: string, truncate: boolean)`:
  - Truncate long addresses for display (bc1q...xyz)
  - Return full address when needed
- Add `formatTransactionType(type: string)` for display labels

#### 5.2 Navigation Helpers
- Create `file:src/navigation/DashboardNavigator.tsx`
- Configure stack navigator with screens:
  - Dashboard (initial route)
  - Send Payment
  - Receive Payment
  - Withdraw
  - Transaction History
  - Transaction Details
- Set up navigation params typing for type safety
- Configure header styles consistent with wireframes

#### 5.3 Constants and Configuration
- Create `file:src/constants/transactions.ts`
- Define transaction type enums matching data model
- Define status enums (pending, confirmed, failed)
- Set pagination constants (PAGE_SIZE = 50)
- Define block explorer URLs (testnet/mainnet)

### 6. Performance Optimizations

#### 6.1 Dashboard Performance
- Implement React.memo for all dashboard components to prevent unnecessary re-renders
- Use useMemo for expensive calculations (balance conversions, date formatting)
- Implement virtualization for recent transactions list (though only 5 items)
- Cache node state in memory with TTL (time-to-live) of 5 seconds
- Prefetch recent transactions on app launch in background
- Use skeleton loaders instead of spinners for better perceived performance

#### 6.2 Transaction List Performance
- Use FlatList/SectionList with proper optimization props:
  - `windowSize={10}` - render 10 screens worth of content
  - `maxToRenderPerBatch={10}` - render 10 items per batch
  - `updateCellsBatchingPeriod={50}` - batch updates every 50ms
  - `removeClippedSubviews={true}` - unmount off-screen items
- Implement `getItemLayout` for consistent item heights (skip measurement)
- Use `keyExtractor` with stable IDs (transaction.id)
- Memoize transaction item components
- Implement database query optimization with proper indexes
- Add request debouncing for search (300ms)

#### 6.3 Caching Strategy
- Implement two-tier caching:
  - **Memory cache**: Recent transactions and node state (fast access)
  - **SQLite cache**: Full transaction history (persistent)
- Set cache invalidation rules:
  - Invalidate on SDK payment events
  - Refresh every 30 seconds in background
  - Force refresh on pull-to-refresh
- Implement optimistic updates for better UX:
  - Update UI immediately on user action
  - Sync with SDK in background
  - Rollback on failure

### 7. Real-time Updates

#### 7.1 SDK Event Listeners
- Register event listeners in `file:src/services/breezSdk.ts`
- Handle `paymentReceived` event:
  - Add new transaction to cache
  - Update dashboard balance
  - Show notification to user
  - Refresh transaction list if visible
- Handle `paymentSent` event:
  - Update transaction status in cache
  - Update dashboard balance
  - Refresh transaction list
- Handle `nodeStateChanged` event:
  - Update balance, liquidity, channel count
  - Refresh dashboard metrics
- Implement event queue to batch rapid updates

#### 7.2 State Synchronization
- Use event emitter pattern to propagate SDK events to UI
- Implement global event bus at `file:src/services/eventBus.ts`
- Subscribe to events in dashboard and transaction screens
- Debounce rapid updates to prevent UI thrashing
- Ensure state consistency between cache and SDK

### 8. Error Handling and Edge Cases

#### 8.1 Error Handling
- Implement error boundary component for crash recovery
- Add try-catch blocks around all SDK calls
- Display user-friendly error messages for common failures:
  - Network disconnection
  - SDK initialization failure
  - Database errors
- Implement retry logic with exponential backoff for transient errors
- Log errors to analytics service for monitoring

#### 8.2 Edge Cases
- Handle empty states:
  - No transactions yet (show onboarding message)
  - No search results (show "No results found")
  - No network connection (show offline indicator)
- Handle pending transactions:
  - Show pending status badge
  - Update when confirmed via SDK event
  - Handle failed transactions
- Handle large transaction lists:
  - Implement pagination to avoid memory issues
  - Lazy load transaction details
- Handle concurrent updates:
  - Use database transactions for atomic updates
  - Implement optimistic locking if needed

### 9. Testing Considerations

#### 9.1 Component Testing
- Test dashboard components render correctly with mock data
- Test transaction list filtering and search functionality
- Test pagination and infinite scroll behavior
- Test pull-to-refresh functionality
- Verify navigation between screens

#### 9.2 Integration Testing
- Test Breez SDK integration with mock SDK responses
- Test SQLite cache operations (CRUD)
- Test event listener registration and handling
- Test state synchronization between cache and SDK
- Verify performance meets 1-second load time requirement

#### 9.3 Data Testing
- Test transaction data model validation
- Test database migrations
- Test cache invalidation logic
- Test data formatting utilities
- Verify data persistence across app restarts

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant Dashboard
    participant Store
    participant Cache
    participant BreezSDK
    
    User->>Dashboard: Open App
    Dashboard->>Store: loadDashboardData()
    Store->>Cache: getCachedTransactions(5)
    Cache-->>Store: Recent 5 transactions
    Store->>BreezSDK: getInfo()
    BreezSDK-->>Store: Node state (balance, liquidity)
    Store-->>Dashboard: Update UI
    Dashboard-->>User: Display (< 1s)
    
    BreezSDK->>Store: paymentReceived event
    Store->>Cache: syncTransactionsToCache()
    Store-->>Dashboard: Update balance & transactions
    Dashboard-->>User: Real-time update
    
    User->>Dashboard: Tap "See All"
    Dashboard->>User: Navigate to Transaction History
    User->>Store: Filter by Lightning
    Store->>Cache: getCachedTransactions(filter, page)
    Cache-->>Store: Filtered transactions
    Store-->>User: Display filtered list
    
    User->>Store: Scroll to bottom
    Store->>Cache: getCachedTransactions(page+1)
    Cache-->>Store: Next 50 transactions
    Store-->>User: Append to list
```

## Component Structure

```
src/
├── screens/
│   ├── DashboardScreen.tsx
│   ├── TransactionHistoryScreen.tsx
│   └── TransactionDetailsScreen.tsx
├── components/
│   ├── dashboard/
│   │   ├── BalanceHeader.tsx
│   │   ├── QuickActions.tsx
│   │   ├── RecentActivity.tsx
│   │   └── StatusBar.tsx
│   └── transactions/
│       ├── SearchBar.tsx
│       ├── FilterTabs.tsx
│       ├── TransactionList.tsx
│       └── TransactionItem.tsx
├── store/
│   ├── dashboardStore.ts
│   └── transactionStore.ts
├── services/
│   ├── breezSdk.ts
│   ├── transactionCache.ts
│   └── eventBus.ts
├── database/
│   └── init.ts
├── utils/
│   └── formatters.ts
├── navigation/
│   └── DashboardNavigator.tsx
└── constants/
    └── transactions.ts
```

---

Execution Information

Branch: main
Commit: 342104b