Enhance documentation for Lightning Wallet integration and real-time features

- Expanded CLAUDE.md to include detailed information about the new Wallet Module, emphasizing its functionality for Lightning wallet management and real-time balance updates.
- Updated README.md to reflect the modular architecture, key features, and real-time wallet capabilities, including WebSocket configuration and connection management.
- Added sections on WebSocket real-time features, including automatic balance updates, live notifications, and battery optimization strategies.

These enhancements improve the clarity and accessibility of the wallet integration documentation, aiding developers in implementation and usage.

CLAUDE.md

@@ -27,6 +27,7 @@ The application uses a plugin-based modular architecture with dependency injecti
 
 **Core Modules:**
 - **Base Module** (`src/modules/base/`) - Core infrastructure (Nostr, Auth, PWA)
+- **Wallet Module** (`src/modules/wallet/`) - Lightning wallet management with real-time balance updates
 - **Nostr Feed Module** (`src/modules/nostr-feed/`) - Social feed functionality
 - **Chat Module** (`src/modules/chat/`) - Encrypted Nostr chat
 - **Events Module** (`src/modules/events/`) - Event ticketing with Lightning payments
@@ -79,7 +80,10 @@ const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
 **Available Services:**
 - `SERVICE_TOKENS.RELAY_HUB` - Centralized Nostr relay management
 - `SERVICE_TOKENS.AUTH_SERVICE` - Authentication services
+- `SERVICE_TOKENS.PAYMENT_SERVICE` - Lightning payment and wallet management
 - `SERVICE_TOKENS.VISIBILITY_SERVICE` - App visibility and connection management
+- `SERVICE_TOKENS.WALLET_SERVICE` - Wallet operations (send, receive, transactions)
+- `SERVICE_TOKENS.WALLET_WEBSOCKET_SERVICE` - Real-time wallet balance updates via WebSocket
 
 **Core Stack:**
 - Vue 3 with Composition API (`<script setup>` style)
@@ -94,6 +98,7 @@ const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
 **Key Features:**
 - Nostr protocol client for decentralized social networking
 - Lightning Network integration for event ticketing
+- **Real-time wallet balance updates via WebSocket** - Automatic UI updates when payments are sent/received
 - PWA capabilities with service worker
 - Theme switching and language switching
 - Real-time connection status monitoring
@@ -113,6 +118,38 @@ const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
 - `src/pages/` - Route pages
 - `electron/` - Electron main process code
 
+**Lightning Wallet Integration:**
+The app integrates with LNbits for Lightning Network wallet functionality with real-time balance updates:
+
+**Core Wallet Services:**
+- `src/core/services/PaymentService.ts` - Centralized payment processing and wallet balance management
+- `src/modules/wallet/services/WalletService.ts` - Wallet operations (send, receive, transactions, pay links)
+- `src/modules/wallet/services/WalletWebSocketService.ts` - **Real-time balance updates via WebSocket**
+
+**WebSocket Real-Time Features:**
+- **Automatic balance updates** when payments are sent or received
+- **Live transaction notifications** with toast messages
+- **Connection management** with automatic reconnection and exponential backoff
+- **Battery optimization** via VisibilityService integration (pauses when app not visible)
+- **Unit conversion handling** between sats and millisats for different LNbits WebSocket behaviors
+
+**WebSocket Configuration** (in `app.config.ts`):
+```typescript
+websocket: {
+  enabled: true,           // Enable/disable WebSocket functionality
+  reconnectDelay: 1000,    // Initial reconnection delay
+  maxReconnectAttempts: 5  // Maximum reconnection attempts
+}
+```
+
+**How WebSocket Balance Updates Work:**
+- Connects to LNbits WebSocket: `wss://your-lnbits/api/v1/ws/{walletInkey}`
+- Handles both incoming and outgoing payment notifications
+- **Incoming payments**: Uses balance as-is (post-payment balance from LNbits)
+- **Outgoing payments**: Adjusts balance by subtracting payment amount (pre-payment balance from LNbits)
+- Updates stored in `PaymentService.updateWalletBalance()` for consistency
+- Triggers Vue reactivity to update UI components immediately
+
 **Nostr Integration:**
 The app connects to Nostr relays using a custom NostrClient class built on nostr-tools. Key files:
 - `src/lib/nostr/client.ts` - Core Nostr client implementation

README.md

@@ -1,5 +1,81 @@
-# Vue 3 + TypeScript + Vite
+# Ario Web App
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+A modular Vue 3 + TypeScript application with Nostr protocol integration and Lightning Network wallet functionality.
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+## Features
+
+- **Modular Architecture**: Plugin-based system with dependency injection
+- **Nostr Integration**: Decentralized social networking and messaging
+- **Lightning Wallet**: Real-time balance updates with LNbits WebSocket integration
+- **Event Ticketing**: Lightning-powered event tickets and marketplace
+- **PWA Support**: Progressive Web App with offline capabilities
+- **Desktop App**: Electron-based desktop application
+
+## Real-Time Wallet Features
+
+The application provides seamless Lightning Network wallet integration:
+
+- **Instant Balance Updates**: WebSocket connection provides real-time balance updates when payments are sent or received
+- **Live Notifications**: Toast notifications for incoming payments
+- **Connection Management**: Automatic reconnection with exponential backoff
+- **Battery Optimization**: Pauses WebSocket when app is not visible to save battery
+- **Multi-Wallet Support**: Manages multiple Lightning wallets with the first wallet as default
+
+### WebSocket Configuration
+
+Configure WebSocket behavior in `src/app.config.ts`:
+
+```typescript
+modules: {
+  wallet: {
+    enabled: true,
+    config: {
+      websocket: {
+        enabled: true,           // Enable/disable real-time updates
+        reconnectDelay: 1000,    // Initial reconnection delay (ms)
+        maxReconnectAttempts: 5  // Maximum reconnection attempts
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Run Electron desktop app
+npm run electron:dev
+```
+
+## Environment Setup
+
+Required environment variables:
+
+```bash
+# LNbits server URL for Lightning wallet functionality
+VITE_LNBITS_BASE_URL=http://localhost:5000
+
+# Nostr relay configuration (JSON array)
+VITE_NOSTR_RELAYS='["wss://relay1.example.com","wss://relay2.example.com"]'
+```
+
+## Architecture
+
+The application follows a modular architecture with the following core modules:
+
+- **Base Module**: Authentication, Nostr client, PWA functionality
+- **Wallet Module**: Lightning payments, WebSocket balance updates, transaction management
+- **Events Module**: Event ticketing with Lightning payment integration
+- **Market Module**: Nostr marketplace functionality
+- **Chat Module**: Encrypted messaging via Nostr
+
+For detailed development guidelines, see [CLAUDE.md](./CLAUDE.md).