web-app/docs/04-development/index.md

# 💻 Development Guide

> **Development workflows and standards** for contributing to Ario's modular Vue 3 + TypeScript application with Nostr and Lightning Network integration.

## Table of Contents

- [[#Development Environment]]
- [[#Development Workflow]]
- [[#Code Standards]]
- [[#Testing Strategy]]
- [[#Build & Deployment]]
- [[#Debugging Guide]]

## Development Environment

### **Prerequisites**
- **Node.js 18+** and npm for package management
- **Git** for version control
- **VS Code** (recommended) with Vue and TypeScript extensions
- **Basic understanding** of Vue 3, TypeScript, and Nostr protocol

### **Quick Setup**
```bash
# Navigate to web app directory
cd web-app/

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# For desktop development
npm run electron:dev
```

### **Environment Configuration**
```bash
# Copy environment template
cp .env.example .env

# Essential configuration
VITE_NOSTR_RELAYS='["wss://relay.damus.io","wss://nos.lol"]'
VITE_ADMIN_PUBKEYS='["admin_pubkey_hex"]'

# Optional configuration
VITE_DEBUG=true
VITE_APP_NAME="Ario Development"
```

### **Development Tools**

#### **Recommended VS Code Extensions**
- **Vue Language Features (Volar)** - Vue 3 support
- **TypeScript Vue Plugin (Volar)** - TypeScript integration
- **Tailwind CSS IntelliSense** - CSS class completion
- **ESLint** - Code linting
- **Prettier** - Code formatting
- **Auto Rename Tag** - HTML tag synchronization

#### **Browser Extensions**
- **Vue.js devtools** - Component inspection and debugging
- **Lightning Network Browser Extension** - WebLN testing

### **Project Structure Overview**
```
web-app/
├── src/
│   ├── components/          # Reusable UI components
│   ├── composables/         # Vue composables and hooks
│   ├── core/               # Core architecture (DI, services)
│   ├── lib/                # Utility functions and helpers
│   ├── modules/            # Feature modules (plugin-based)
│   ├── pages/              # Route pages
│   ├── stores/             # Pinia state management
│   └── types/              # TypeScript type definitions
├── docs/                   # Documentation (Obsidian-style)
├── public/                 # Static assets
├── electron/               # Electron main process
└── tests/                  # Test files
```

## Development Workflow

### **Feature Development Process**

#### **1. Planning & Design**
- Review existing modules and services for reusable functionality
- Design module interfaces and dependencies
- Create or update relevant documentation

#### **2. Implementation**
```bash
# Create feature branch
git checkout -b feature/my-new-feature

# Implement feature following modular architecture
# - Create module plugin if needed
# - Implement services with BaseService pattern
# - Use dependency injection for service access
# - Follow TypeScript and Vue 3 best practices

# Test implementation
npm run dev
npm run test:unit  # If tests exist
```

#### **3. Code Review & Testing**
```bash
# Run quality checks
npm run build      # Ensure TypeScript compilation
npm run lint       # Check code style
npm run format     # Auto-format code

# Test across platforms
npm run preview           # Test production build
npm run electron:dev      # Test desktop version
```

#### **4. Documentation & Commit**
```bash
# Update relevant documentation
# Add JSDoc comments for public APIs
# Update CHANGELOG.md if applicable

# Commit with conventional commits
git add .
git commit -m "feat: add new feature functionality"
```

### **Daily Development Tasks**

#### **Starting Development Session**
```bash
cd web-app/
npm run dev  # Starts Vite dev server on http://localhost:5173
```

#### **Development Server Features**
- **Hot Module Replacement (HMR)** - Instant updates without page reload
- **TypeScript Checking** - Compile-time error detection
- **Import Analysis** - Automatic dependency resolution
- **Source Maps** - Debug original TypeScript code in browser

#### **Common Development Commands**
```bash
# Development
npm run dev                # Start dev server
npm run dev:host          # Dev server accessible on network

# Building
npm run build             # Production build with TypeScript check
npm run preview           # Preview production build locally

# Code Quality
npm run lint              # ESLint checking
npm run lint:fix          # Auto-fix linting issues
npm run format            # Prettier formatting

# Electron
npm run electron:dev      # Concurrent Vite + Electron development
npm run electron:build    # Package desktop application

# Analysis
npm run analyze           # Bundle analyzer
```

## Code Standards

### **TypeScript Guidelines**

#### **Strict Type Checking**
```typescript
// ✅ Use explicit types for public APIs
interface UserProfile {
  pubkey: string
  name?: string
  about?: string
}

// ✅ Use type guards for runtime validation
function isNostrEvent(obj: unknown): obj is NostrEvent {
  return typeof obj === 'object' && obj !== null && 'kind' in obj
}

// ❌ Avoid 'any' type
function processData(data: any): any { }

// ✅ Use proper generic constraints
function processData<T extends NostrEvent>(data: T): T { }
```

#### **Interface vs Type Preferences**
```typescript
// ✅ Use interfaces for extensible objects
interface ModulePlugin {
  name: string
  install(app: App): Promise<void>
}

interface MyModulePlugin extends ModulePlugin {
  customConfig?: MyConfig
}

// ✅ Use type aliases for unions and computations
type EventKind = 0 | 1 | 3 | 4 | 5 | 6 | 7
type ServiceToken = keyof typeof SERVICE_TOKENS
```

### **Vue 3 Patterns**

#### **Composition API with Script Setup**
```vue
<script setup lang="ts">
// ✅ Use <script setup> syntax
import { ref, computed, onMounted } from 'vue'

// Props with TypeScript
interface Props {
  userId: string
  initialData?: UserData
}
const props = defineProps<Props>()

// Reactive state
const data = ref<UserData[]>([])
const loading = ref(false)

// Computed properties
const filteredData = computed(() => 
  data.value.filter(item => item.userId === props.userId)
)

// Lifecycle hooks
onMounted(async () => {
  await loadUserData()
})
</script>
```

#### **Service Integration**
```vue
<script setup lang="ts">
// ✅ Use dependency injection for services
const authService = injectService(SERVICE_TOKENS.AUTH_SERVICE)
const toast = injectService(SERVICE_TOKENS.TOAST_SERVICE)

// ✅ Destructure reactive properties
const { user, isAuthenticated } = authService

// ✅ Handle async operations properly
const handleLogin = async () => {
  try {
    await authService.login(privateKey.value)
    toast.auth.loginSuccess()
  } catch (error) {
    toast.auth.loginError(error.message)
  }
}
</script>
```

### **Module Development Standards**

#### **Module Structure**
```typescript
// ✅ Proper module plugin implementation
export const myModule: ModulePlugin = {
  name: 'my-module',
  version: '1.0.0',
  dependencies: ['base'], // Always depend on base
  
  async install(app: App, options?: MyModuleConfig) {
    // Register services
    const myService = new MyService()
    container.provide(SERVICE_TOKENS.MY_SERVICE, myService)
    
    // Register components
    app.component('MyComponent', MyComponent)
    
    // Initialize
    await myService.initialize()
  },
  
  routes: [
    {
      path: '/my-feature',
      component: () => import('./views/MyFeatureView.vue')
    }
  ]
}
```

#### **Service Development**
```typescript
// ✅ Extend BaseService for consistency
export class MyService extends BaseService {
  private readonly _data = ref<MyData[]>([])
  public readonly data = readonly(this._data)
  
  constructor(
    private auth = injectService(SERVICE_TOKENS.AUTH_SERVICE)
  ) {
    super()
  }
  
  async initialize(): Promise<void> {
    // Initialization logic
    this.isInitialized.value = true
  }
  
  async dispose(): Promise<void> {
    // Cleanup logic
    this.isDisposed.value = true
  }
}
```

### **Naming Conventions**

#### **Files and Directories**
```
# ✅ Use kebab-case for files and directories
my-component.vue
my-service.ts
my-module-config.ts

# ✅ Component files use PascalCase base name
UserProfileCard.vue
EventTicketPurchase.vue
```

#### **Variables and Functions**
```typescript
// ✅ Use camelCase for variables and functions
const userName = ref('')
const isAuthenticated = computed(() => !!user.value)

async function handleUserLogin(): Promise<void> { }

// ✅ Use PascalCase for classes and interfaces
class AuthService extends BaseService { }
interface UserProfile { }
```

#### **Constants and Types**
```typescript
// ✅ Use SCREAMING_SNAKE_CASE for constants
const MAX_MESSAGE_LENGTH = 1000
const DEFAULT_RELAY_URLS = ['wss://relay.example.com']

// ✅ Use PascalCase for types and enums
type NostrEventKind = 0 | 1 | 3 | 4
enum ConnectionStatus { Connected, Connecting, Disconnected }
```

## Testing Strategy

### **Testing Philosophy**
- **Unit Tests** - Test individual components and services in isolation
- **Integration Tests** - Test service interactions and module integration
- **E2E Tests** - Test complete user workflows (planned)
- **Manual Testing** - Cross-platform testing and user experience validation

### **Unit Testing Setup**
```typescript
// tests/unit/services/MyService.test.ts
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { MyService } from '@/services/MyService'
import { createMockDIContainer } from '@/tests/helpers'

describe('MyService', () => {
  let service: MyService
  let mockAuth: MockAuthService
  
  beforeEach(() => {
    const container = createMockDIContainer()
    mockAuth = container.get(SERVICE_TOKENS.AUTH_SERVICE)
    service = new MyService()
  })
  
  afterEach(async () => {
    await service.dispose()
  })
  
  it('should initialize correctly', async () => {
    await service.initialize()
    expect(service.isInitialized.value).toBe(true)
  })
})
```

### **Component Testing**
```typescript
// tests/unit/components/MyComponent.test.ts
import { mount } from '@vue/test-utils'
import { createMockDIContainer } from '@/tests/helpers'
import MyComponent from '@/components/MyComponent.vue'

describe('MyComponent', () => {
  it('should render correctly', () => {
    const wrapper = mount(MyComponent, {
      props: { userId: 'test-user' },
      global: {
        plugins: [createMockDIContainer()]
      }
    })
    
    expect(wrapper.text()).toContain('test-user')
  })
})
```

## Build & Deployment

### **Development Builds**
```bash
# Development server (with HMR)
npm run dev

# Development build (for debugging)
npm run build:dev
```

### **Production Builds**
```bash
# Full production build
npm run build

# Preview production build locally
npm run preview

# Bundle analysis
npm run analyze
```

### **Electron Builds**
```bash
# Development
npm run electron:dev

# Production packaging
npm run electron:build

# Platform-specific builds
npm run build:win    # Windows
npm run build:mac    # macOS  
npm run build:linux  # Linux
```

### **Build Configuration**

#### **Vite Configuration** (`vite.config.ts`)
- **TypeScript compilation** with vue-tsc
- **Bundle optimization** with manual chunking
- **PWA integration** with service worker
- **Asset optimization** with image processing

#### **Electron Configuration** (`forge.config.js`)
- **Cross-platform packaging** with Electron Forge
- **Auto-updater integration** for seamless updates
- **Code signing** for distribution (production)

## Debugging Guide

### **Development Debugging**

#### **Vue DevTools**
- Install Vue DevTools browser extension
- Inspect component state and props
- Monitor Pinia store mutations
- Track component lifecycle events

#### **Browser Developer Tools**
- Use TypeScript source maps for original code debugging
- Network tab for Nostr relay communication
- Console tab for service logging
- Application tab for localStorage inspection

#### **Service Debugging**
```typescript
// Add debug logging to services
export class MyService extends BaseService {
  private debug = (message: string, ...args: unknown[]) => {
    if (import.meta.env.VITE_DEBUG) {
      console.log(`[MyService] ${message}`, ...args)
    }
  }
  
  async performAction(): Promise<void> {
    this.debug('Performing action...')
    // Implementation
    this.debug('Action completed')
  }
}
```

### **Nostr Debugging**

#### **Relay Communication**
```typescript
// Log Nostr events for debugging
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)

relayHub.subscribe(filters, (event) => {
  console.log('Received Nostr event:', event)
})

// Debug relay connections
console.log('Connected relays:', relayHub.connectedRelays.value)
```

#### **Event Publishing**
```typescript
// Debug event publishing
try {
  await relayHub.publishEvent(event)
  console.log('Event published successfully:', event)
} catch (error) {
  console.error('Failed to publish event:', error)
}
```

### **Common Issues & Solutions**

#### **TypeScript Errors**
```bash
# Clear TypeScript cache
rm -rf node_modules/.cache
rm -rf dist

# Restart TypeScript language server in VS Code
Cmd/Ctrl + Shift + P > "TypeScript: Restart TS Server"
```

#### **Module Import Issues**
```typescript
// ❌ Incorrect relative import
import { MyService } from '../../services/MyService'

// ✅ Use absolute imports with @ alias
import { MyService } from '@/services/MyService'
```

#### **Dependency Injection Issues**
```typescript
// ❌ Service not registered
const service = injectService(SERVICE_TOKENS.MY_SERVICE) // Error!

// ✅ Ensure service is registered in module installation
container.provide(SERVICE_TOKENS.MY_SERVICE, new MyService())
```

## See Also

### Development Documentation
- **[[setup|🛠️ Environment Setup]]** - Detailed setup instructions
- **[[coding-standards|📋 Coding Standards]]** - Comprehensive style guide
- **[[testing|🧪 Testing Guide]]** - Testing frameworks and patterns
- **[[debugging|🐛 Debugging Techniques]]** - Advanced debugging strategies

### Architecture References
- **[[../02-modules/index|📦 Module System]]** - Plugin-based architecture
- **[[../03-core-services/index|⚙️ Core Services]]** - Service development patterns
- **[[../01-architecture/dependency-injection|⚙️ Dependency Injection]]** - DI container usage

---

**Tags:** #development #workflow #standards #testing #debugging  
**Last Updated:** 2025-09-06  
**Author:** Development Team