web-app/docs/02-modules/index.md

# 📦 Module System Overview

> **Modular architecture** enabling feature-based development with plugin-based modules, dependency injection, and clean separation of concerns.

## Table of Contents

- [[#Module Architecture]]
- [[#Available Modules]]
- [[#Module Development]]
- [[#Module Configuration]]
- [[#Inter-Module Communication]]
- [[#Module Lifecycle]]

## Module Architecture

### **Plugin-Based Design**
Ario uses a plugin-based architecture where each feature is implemented as a self-contained module:

- **Independent Development** - Modules can be developed, tested, and deployed separately
- **Optional Features** - Modules can be enabled or disabled via configuration
- **Clear Boundaries** - Each module owns its domain logic and UI components
- **Extensible** - New modules can be added without modifying existing code

### **Module Structure**
Each module follows a consistent directory structure:
```
src/modules/[module-name]/
├── index.ts                 # Module plugin definition
├── components/              # Module-specific UI components
├── composables/             # Module composables and hooks
├── services/               # Business logic and API services
├── stores/                 # Module-specific Pinia stores
├── types/                  # TypeScript type definitions
└── views/                  # Page components and routes
```

### **Module Plugin Interface**
All modules implement the `ModulePlugin` interface:
```typescript
interface ModulePlugin {
  name: string              // Unique module identifier
  version: string           // Semantic version
  dependencies: string[]    // Required module dependencies
  
  // Installation lifecycle
  install(app: App, options?: ModuleConfig): Promise<void>
  
  // Optional exports
  routes?: RouteRecordRaw[]           // Vue Router routes
  components?: Record<string, any>    // Global components  
  composables?: Record<string, any>   // Exported composables
}
```

## Available Modules

### **Base Module** 🏗️
**Purpose:** Core infrastructure and shared services  
**Location:** `src/modules/base/`  
**Dependencies:** None (foundation module)

**Provides:**
- **Authentication Service** - User identity management and Nostr key handling
- **Relay Hub** - Centralized Nostr relay connection management
- **Storage Service** - User-scoped localStorage operations
- **Toast Service** - Application-wide notifications and feedback
- **PWA Features** - Service worker and offline capabilities

**Key Components:**
- Identity management UI (key generation, import/export)
- Connection status indicators
- Theme and language switching
- Authentication guards and utilities

**See:** [[base-module/index|📖 Base Module Documentation]]

### **Wallet Module** 💰
**Purpose:** Lightning Network wallet management with real-time updates
**Location:** `src/modules/wallet/`
**Dependencies:** `['base']`

**Features:**
- **Real-time Balance Updates** - WebSocket connection to LNbits for instant balance sync
- **Payment Processing** - Send to Lightning invoices, addresses, and LNURL endpoints
- **Transaction Management** - Comprehensive history with real-time transaction updates
- **Payment Links** - Create LNURL payment links and Lightning addresses for receiving
- **Multi-wallet Support** - Manage multiple wallets with automatic selection
- **Battery Optimization** - Pauses WebSocket when app not visible to save battery

**Key Components:**
- SendDialog for payment sending interface
- ReceiveDialog for payment link creation
- TransactionList with real-time updates
- BalanceDisplay with WebSocket synchronization
- PayLinkManager for LNURL link management

**WebSocket Integration:**
- Real-time balance updates via LNbits WebSocket API
- Smart unit conversion handling (sats/millisats)
- Automatic reconnection with exponential backoff
- VisibilityService integration for mobile battery optimization

**See:** [[wallet-module/index|📖 Wallet Module Documentation]]

### **Nostr Feed Module** 📰
**Purpose:** Social feed and content discovery  
**Location:** `src/modules/nostr-feed/`  
**Dependencies:** `['base']`

**Features:**
- **Social Feed** - Timeline of Nostr events (kind 1 notes)
- **Admin Announcements** - Highlighted posts from configured admin pubkeys
- **Content Filtering** - Filter by author, content type, or keywords
- **Real-time Updates** - Live feed updates via Nostr subscriptions
- **Engagement** - Like, repost, and reply to posts

**Key Components:**
- FeedComponent with infinite scroll
- NoteCard for individual posts
- AdminBadge for announcement highlighting
- Content filtering and search

**See:** [[nostr-feed-module/index|📖 Nostr Feed Documentation]]

### **Chat Module** 💬
**Purpose:** Encrypted direct messaging  
**Location:** `src/modules/chat/`  
**Dependencies:** `['base']`

**Features:**
- **Encrypted Messages** - NIP-04 encrypted direct messages
- **Contact Management** - Add and manage chat contacts
- **Real-time Chat** - Live message delivery via Nostr relays
- **Message History** - Persistent chat history with local storage
- **Typing Indicators** - Real-time typing status (when supported)

**Key Components:**
- ChatComponent with message bubbles
- ContactList for chat participants
- MessageInput with encryption handling
- Chat history management

**See:** [[chat-module/index|📖 Chat Module Documentation]]

### **Events Module** 🎟️
**Purpose:** Event ticketing and management  
**Location:** `src/modules/events/`  
**Dependencies:** `['base']`

**Features:**
- **Event Creation** - Create and publish events to Nostr
- **Lightning Tickets** - Paid event tickets using Lightning invoices
- **Event Discovery** - Browse and search upcoming events
- **Ticket Management** - Purchase, transfer, and validate tickets
- **Event Check-in** - QR code-based event entry system

**Key Components:**
- EventCard for event display
- TicketPurchase with Lightning payment flow
- EventCreation form with rich editing
- QR code generation and scanning

**See:** [[events-module/index|📖 Events Module Documentation]]

### **Market Module** 🛒
**Purpose:** Nostr marketplace functionality  
**Location:** `src/modules/market/`  
**Dependencies:** `['base']`

**Features:**
- **Product Listings** - Create and browse marketplace items
- **Lightning Payments** - Bitcoin payments for products
- **Vendor Profiles** - Seller reputation and product history
- **Order Management** - Track purchases and sales
- **Product Search** - Filter and search marketplace items

**Key Components:**
- ProductCard for item display
- ProductListing creation form
- OrderHistory and transaction tracking
- Vendor dashboard and analytics

**See:** [[market-module/index|📖 Market Module Documentation]]

## Module Development

### **Creating a New Module**

#### 1. Module Structure Setup
```bash
mkdir src/modules/my-module
cd src/modules/my-module

# Create module directories
mkdir components composables services stores types views
touch index.ts
```

#### 2. Module Plugin Definition
```typescript
// src/modules/my-module/index.ts
import type { App } from 'vue'
import type { ModulePlugin } from '@/core/types'

export const myModule: ModulePlugin = {
  name: 'my-module',
  version: '1.0.0',
  dependencies: ['base'], // Always depend on base for core services
  
  async install(app: App, options?: MyModuleConfig) {
    // Register module components
    // Initialize module services  
    // Set up module routes
  },
  
  routes: [
    {
      path: '/my-feature',
      component: () => import('./views/MyFeatureView.vue')
    }
  ]
}
```

#### 3. Service Implementation
```typescript
// src/modules/my-module/services/my-service.ts
import { BaseService } from '@/core/base/BaseService'
import { injectService, SERVICE_TOKENS } from '@/core/di-container'

export class MyService extends BaseService {
  constructor(
    private relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
  ) {
    super()
  }
  
  async initialize(): Promise<void> {
    // Service initialization logic
    this.isInitialized.value = true
  }
  
  async dispose(): Promise<void> {
    // Cleanup logic
    this.isDisposed.value = true
  }
}
```

#### 4. Module Registration
```typescript
// src/app.config.ts
export const moduleConfigs = {
  // ... existing modules
  'my-module': {
    enabled: true,
    customOption: 'value'
  }
}
```

### **Module Development Best Practices**

#### **Dependency Management**
- Always declare module dependencies explicitly
- Use dependency injection for cross-module service access
- Avoid direct imports between modules

#### **Service Architecture**
- Extend `BaseService` for consistent lifecycle management
- Register services in the DI container during module installation
- Use reactive properties for state that affects UI

#### **Component Patterns**
- Export reusable components for other modules
- Use module-specific component naming (e.g., `ChatMessage`, `EventCard`)
- Follow the existing UI component patterns with Shadcn/ui

## Module Configuration

### **Configuration Schema**
Modules can be configured via `src/app.config.ts`:
```typescript
interface ModuleConfig {
  enabled: boolean          // Enable/disable module
  [key: string]: any       // Module-specific configuration
}

export const moduleConfigs: Record<string, ModuleConfig> = {
  'base': { enabled: true },
  'chat': { 
    enabled: true,
    maxMessageLength: 1000,
    enableTypingIndicators: true
  },
  'events': {
    enabled: true,
    defaultCurrency: 'sat',
    allowedEventTypes: ['meetup', 'conference', 'workshop']
  }
}
```

### **Runtime Configuration**
Configuration is passed to modules during installation:
```typescript
async install(app: App, options?: ChatModuleConfig) {
  const config = options || defaultConfig
  
  // Use configuration to customize module behavior
  this.messageService.setMaxLength(config.maxMessageLength)
}
```

## Inter-Module Communication

### **Service Dependencies**
For required functionality between modules:
```typescript
// ✅ Correct: Use dependency injection
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)

// ❌ Wrong: Direct import breaks modularity
import { relayHub } from '../base/services/relay-hub'
```

### **Event Bus Communication**
For optional cross-module notifications:
```typescript
// Publishing events
eventBus.emit('user:authenticated', { userId: user.pubkey })
eventBus.emit('payment:received', { amount: 1000, invoiceId: 'abc123' })

// Subscribing to events
eventBus.on('chat:message-received', (message) => {
  // Handle message in events module
})
```

### **Shared Components**
Modules can export components for use by other modules:
```typescript
// In module plugin definition
export const chatModule: ModulePlugin = {
  // ...
  components: {
    'ChatAvatar': () => import('./components/ChatAvatar.vue'),
    'MessageBubble': () => import('./components/MessageBubble.vue')
  }
}

// Usage in other modules
<ChatAvatar :pubkey="user.pubkey" :size="32" />
```

## Module Lifecycle

### **Initialization Order**
1. **Dependency Resolution** - PluginManager sorts modules by dependencies
2. **Service Registration** - Modules register services in DI container
3. **Component Registration** - Global components made available
4. **Route Registration** - Module routes added to Vue Router
5. **Service Initialization** - Services initialize in dependency order

### **Module Installation Process**
```typescript
async install(app: App, options?: ModuleConfig) {
  // 1. Register services
  container.provide(SERVICE_TOKENS.MY_SERVICE, new MyService())
  
  // 2. Register global components
  app.component('MyGlobalComponent', MyGlobalComponent)
  
  // 3. Initialize module-specific logic
  await this.initializeModule(options)
}
```

### **Service Lifecycle Management**
```typescript
// Service initialization (called automatically)
async initialize(): Promise<void> {
  await this.setupEventListeners()
  await this.loadUserData()
  this.isInitialized.value = true
}

// Service disposal (called on app unmount)
async dispose(): Promise<void> {
  this.removeEventListeners()
  await this.saveUserData()
  this.isDisposed.value = true
}
```

## See Also

### Module Documentation
- **[[base-module/index|🏗️ Base Module]]** - Core infrastructure services
- **[[wallet-module/index|💰 Wallet Module]]** - Lightning wallet with real-time updates
- **[[chat-module/index|💬 Chat Module]]** - Encrypted messaging system
- **[[events-module/index|🎟️ Events Module]]** - Lightning event ticketing
- **[[market-module/index|🛒 Market Module]]** - Nostr marketplace
- **[[nostr-feed-module/index|📰 Nostr Feed]]** - Social feed functionality

### Architecture References
- **[[../01-architecture/modular-design|🔧 Modular Design Patterns]]** - Architecture principles
- **[[../01-architecture/dependency-injection|⚙️ Dependency Injection]]** - Service container system
- **[[../04-development/index|💻 Development Guide]]** - Module development workflows

---

**Tags:** #modules #architecture #plugin-system #development  
**Last Updated:** 2025-09-06  
**Author:** Development Team