web-app/docs/01-architecture/index.md

# 🏗️ Architecture Overview

> **System design and patterns** powering Ario's modular, scalable, and maintainable architecture with dependency injection, plugin-based modules, and reactive services.

## Table of Contents

- [[#Architecture Principles]]
- [[#Core Systems]]
- [[#Service Architecture]]
- [[#Module System]]
- [[#Communication Patterns]]
- [[#Data Flow]]

## Architecture Principles

### **Modularity** - Plugin-Based Design
Every feature is implemented as a self-contained module that can be enabled, disabled, or configured independently. This approach ensures:
- **Separation of Concerns** - Each module owns its domain logic
- **Testability** - Modules can be tested in isolation
- **Maintainability** - Changes to one module don't affect others
- **Extensibility** - New features can be added as plugins

### **Loose Coupling** - Dependency Injection
Services communicate through well-defined interfaces using a dependency injection container:
- **Interface-Based Design** - Services depend on abstractions, not implementations
- **Runtime Configuration** - Service instances can be swapped for testing or different environments
- **Clear Dependencies** - Service relationships are explicit and manageable
- **Lifecycle Management** - Services have defined initialization and disposal phases

### **Reactive Architecture** - Vue-Powered Services
Services integrate Vue's reactivity system for state management:
- **Reactive State** - Services expose reactive refs and computed properties
- **Automatic Updates** - UI automatically updates when service state changes
- **Event-Driven Communication** - Services communicate via event bus patterns
- **Consistent Patterns** - Same reactivity patterns used throughout the application

## Core Systems

### **Dependency Injection Container**
Location: `src/core/di-container.ts`

Centralized service registry and resolution system:
```typescript
// Service registration (in modules)
container.provide(SERVICE_TOKENS.RELAY_HUB, relayHub)

// Service consumption (anywhere)
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
```

**Key Features:**
- Type-safe service tokens
- Singleton lifecycle management
- Runtime service validation
- Development-time debugging support

### **Plugin Manager**
Location: `src/core/plugin-manager.ts`

Orchestrates module loading and dependency resolution:
```typescript
class PluginManager {
  async loadModule(plugin: ModulePlugin): Promise<void>
  getDependencyGraph(): Map<string, string[]>
  validateDependencies(modules: ModulePlugin[]): void
}
```

### **Base Service Architecture**
Location: `src/core/base/BaseService.ts`

Abstract foundation for all services with common patterns:
```typescript
abstract class BaseService {
  protected isInitialized = ref(false)
  protected isDisposed = ref(false)
  
  abstract initialize(): Promise<void>
  abstract dispose(): Promise<void>
}
```

## Service Architecture

### **Service Categories**

#### **Infrastructure Services** (Base Module)
- **RelayHub** - Nostr relay connection management
- **AuthService** - User authentication and key management  
- **StorageService** - User-scoped local storage operations
- **ToastService** - User notifications and feedback

#### **Feature Services** (Module-Specific)
- **ChatService** - Encrypted messaging functionality
- **MarketService** - Marketplace operations
- **EventsService** - Event creation and ticketing
- **FeedService** - Social feed management

### **Service Communication Patterns**

#### **Direct Service Dependencies**
For tightly coupled operations:
```typescript
class ChatService extends BaseService {
  constructor(
    private relayHub = injectService(SERVICE_TOKENS.RELAY_HUB),
    private auth = injectService(SERVICE_TOKENS.AUTH_SERVICE)
  ) {}
}
```

#### **Event Bus Communication**
For loose coupling between modules:
```typescript
// Publishing events
eventBus.emit('user:authenticated', { userId: user.pubkey })

// Subscribing to events
eventBus.on('payment:received', handlePaymentReceived)
```

## Module System

### **Module Plugin Structure**
Each module implements the `ModulePlugin` interface:
```typescript
interface ModulePlugin {
  name: string
  version: string
  dependencies: string[]
  
  install(app: App, options?: any): Promise<void>
  routes?: RouteRecordRaw[]
  components?: Record<string, Component>
}
```

### **Module Categories**

#### **Base Module** - Core Infrastructure
- **Purpose** - Provides shared services and infrastructure
- **Dependencies** - None (foundation module)
- **Exports** - RelayHub, AuthService, StorageService, ToastService

#### **Feature Modules** - Domain-Specific Logic  
- **Chat Module** - Encrypted messaging with Nostr DMs
- **Events Module** - Event creation and Lightning ticketing
- **Market Module** - Nostr marketplace functionality
- **Nostr Feed Module** - Social feed and content discovery

### **Module Configuration**
Location: `src/app.config.ts`
```typescript
export const moduleConfigs = {
  'base': { enabled: true },
  'chat': { enabled: true, maxMessageLength: 1000 },
  'events': { enabled: true, defaultCurrency: 'sat' },
  'market': { enabled: true, allowedCategories: ['all'] },
  'nostr-feed': { enabled: true, defaultRelays: [] }
}
```

## Communication Patterns

### **Service-to-Service Communication**
```typescript
// 1. Direct injection for required dependencies
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)

// 2. Event bus for optional/cross-module communication
eventBus.emit('user:profile-updated', profileData)

// 3. Reactive refs for state sharing
const connectionStatus = computed(() => relayHub.connectionStatus.value)
```

### **Component-to-Service Communication**
```typescript
// 1. Composables wrap service access
const { publishNote, isPublishing } = useNoteComposer()

// 2. Direct service injection in components
const toastService = injectService(SERVICE_TOKENS.TOAST_SERVICE)

// 3. Store integration for component state
const authStore = useAuthStore()
```

### **Module-to-Module Communication**
```typescript
// ❌ Direct imports break modularity
import { chatService } from '../chat/services/chat-service'

// ✅ Dependency injection maintains loose coupling
const chatService = injectService(SERVICE_TOKENS.CHAT_SERVICE)

// ✅ Event bus for cross-module notifications
eventBus.emit('chat:message-received', messageData)
```

## Data Flow

### **Nostr Event Lifecycle**
1. **Event Creation** - User action triggers event creation
2. **Event Signing** - AuthService signs event with user's private key
3. **Relay Publishing** - RelayHub publishes to configured relays
4. **Event Storage** - StorageService caches event locally
5. **UI Updates** - Reactive properties trigger component re-renders

### **Lightning Payment Flow**
1. **Invoice Generation** - EventsService creates Lightning invoice
2. **QR Code Display** - UI presents payment interface
3. **Payment Detection** - WebLN or external wallet processes payment
4. **Verification** - Service confirms payment via Lightning backend
5. **State Updates** - Payment success triggers relevant service updates

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

## See Also

### Deep Dive Documentation
- **[[modular-design|📦 Modular Design Patterns]]** - Plugin architecture details
- **[[dependency-injection|⚙️ Dependency Injection]]** - Service container system
- **[[relay-hub|🌐 Relay Hub Architecture]]** - Nostr relay management
- **[[event-bus|📡 Event Bus Communication]]** - Inter-module messaging

### Implementation References
- **[[../02-modules/index|📦 Module Documentation]]** - Individual module guides
- **[[../03-core-services/index|⚙️ Core Services]]** - Service implementations
- **[[../04-development/index|💻 Development Guide]]** - Architectural patterns in practice

---

**Tags:** #architecture #design-patterns #modularity #dependency-injection  
**Last Updated:** 2025-09-06  
**Author:** Development Team