From 23726f09ec04b711292ac06cb62cb9c482872544 Mon Sep 17 00:00:00 2001
From: padreug <padreug@aiolabs.dev>
Date: Thu, 18 Sep 2025 09:56:55 +0200
Subject: [PATCH] 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 | 37 +++++++++++++++++++++++++
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 116 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 185930d..cb789c6 100644
--- a/CLAUDE.md
+++ b/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
diff --git a/README.md b/README.md
index 33895ab..d595888 100644
--- a/README.md
+++ b/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).