web-app/docs/00-overview/tech-stack.md

# 🛠️ Technology Stack

> **Modern web technologies** powering Ario's decentralized architecture with Vue 3, TypeScript, Nostr, and Lightning Network integration.

## Table of Contents

- [[#Frontend Core]]
- [[#State Management & Routing]]
- [[#Styling & UI Components]]
- [[#Nostr & Lightning Integration]]
- [[#Build Tools & Development]]
- [[#Desktop & PWA]]
- [[#Architecture Patterns]]

## Frontend Core

### **Vue 3** - Progressive JavaScript Framework
- **Composition API** with `<script setup>` syntax for optimal DX
- **Reactivity System** with `ref()`, `reactive()`, and `computed()`
- **Component Architecture** with Single File Components (SFCs)
- **Template Compilation** for optimized runtime performance

**Why Vue 3?**
- Excellent TypeScript integration
- Composition API enables better code reuse
- Small bundle size and fast performance
- Great developer experience with Vite

### **TypeScript** - Type-Safe JavaScript
- **Strict Type Checking** throughout the application
- **Interface-Based Architecture** for better code contracts
- **Generic Types** for reusable service patterns
- **Compile-Time Error Detection** preventing runtime issues

**Configuration:**
```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}
```

### **Vite** - Next-Generation Build Tool
- **Lightning-Fast Dev Server** with HMR (Hot Module Replacement)
- **Optimized Production Builds** with Rollup
- **Plugin Ecosystem** for Vue, TypeScript, and PWA support
- **ES Modules** native support for modern browsers

## State Management & Routing

### **Pinia** - Vue Store Library
- **Composition API Integration** for consistent patterns
- **TypeScript Support** with full type inference
- **Devtools Integration** for debugging
- **Server-Side Rendering** compatibility

**Store Pattern Example:**
```typescript
export const useAuthStore = defineStore('auth', () => {
  const user = ref<NostrUser | null>(null)
  const isAuthenticated = computed(() => !!user.value)
  
  const login = async (privateKey: string) => {
    // Authentication logic
  }
  
  return { user, isAuthenticated, login }
})
```

### **Vue Router** - Client-Side Routing
- **File-Based Routing** with automatic route generation
- **Route Guards** for authentication and authorization
- **Lazy Loading** for code-splitting by route
- **Nested Routes** for complex layout structures

### **Vue-i18n** - Internationalization
- **Reactive Language Switching** with Composition API
- **Pluralization Support** for different languages
- **Number and Date Formatting** localization
- **Lazy Loading** of translation files

## Styling & UI Components

### **TailwindCSS v4** - Utility-First CSS Framework
- **Design System** with consistent spacing and typography
- **Dark Mode Support** with CSS variables
- **Component Variants** using Tailwind's class composition
- **Optimized Builds** with unused CSS elimination

### **Shadcn/ui** - High-Quality Component Library
- **Accessible Components** following WAI-ARIA guidelines
- **Customizable Styling** with CSS variables and Tailwind
- **Copy-Paste Architecture** rather than npm dependencies
- **TypeScript Support** with proper type definitions

**Component Structure:**
```
src/components/ui/
├── button/           # Button variants and sizes
├── card/            # Card layouts and containers
├── dialog/          # Modal and dialog components
├── form/            # Form inputs and validation
└── toast/           # Notification components
```

## Nostr & Lightning Integration

### **Nostr Protocol** - Decentralized Social Protocol
- **nostr-tools** - Core Nostr client implementation
- **Event Publishing** and subscription management
- **Key Management** with secure client-side storage
- **Relay Management** with connection pooling and fallback

**Nostr Client Architecture:**
```typescript
class NostrClient {
  private pool: RelayPool
  private subscriptions: Map<string, Sub>
  
  async publishEvent(event: Event): Promise<void>
  subscribe(filters: Filter[], onEvent: EventHandler): Sub
  connect(relays: string[]): Promise<void>
}
```

### **Lightning Network** - Bitcoin Payment Layer
- **WebLN Integration** for browser-based Lightning wallets
- **Invoice Generation** with QR code support  
- **Payment Verification** and status tracking
- **LNbits Integration** for wallet backend services

### **QR Code Generation** - Payment Interfaces
- **Lightning Invoice QR Codes** for mobile wallet scanning
- **Contact Information Sharing** with Nostr public keys
- **Event Tickets** with embedded payment information

## Build Tools & Development

### **Vite Configuration**
- **Plugin Architecture** with Vue, TypeScript, and PWA plugins
- **Code Splitting** with manual chunk optimization
- **Asset Optimization** with image processing and compression
- **Development Server** with proxy configuration for API calls

**Bundle Analysis:**
```bash
npm run analyze  # Opens bundle analyzer visualization
```

### **ESLint + Prettier** - Code Quality
- **Vue-Specific Rules** for SFC linting
- **TypeScript Integration** with type-aware linting
- **Automatic Formatting** on save and commit
- **Import Sorting** and unused import removal

### **Git Hooks** - Pre-commit Quality Gates
- **Type Checking** before commits
- **Linting** and formatting validation
- **Test Execution** for modified files
- **Build Verification** to catch issues early

## Desktop & PWA

### **Electron** - Cross-Platform Desktop Apps
- **Electron Forge** for packaging and distribution
- **Auto-Update** functionality for seamless updates
- **Native Menus** and system tray integration
- **File System Access** for local data storage

### **PWA (Progressive Web App)**
- **Service Worker** with caching strategies
- **App Manifest** for installation and app-like experience
- **Offline Support** with background sync
- **Push Notifications** for real-time updates

**PWA Configuration:**
```typescript
// vite.config.ts
VitePWA({
  registerType: 'autoUpdate',
  workbox: {
    globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}']
  }
})
```

## Architecture Patterns

### **Dependency Injection** - Service Management
- **DI Container** for service registration and resolution
- **Service Tokens** for type-safe service access
- **Lifecycle Management** with initialization and disposal
- **Testing Support** with mock service injection

### **Module Plugin System** - Extensible Architecture
- **Module Registration** with dependency management
- **Route Configuration** per module
- **Service Isolation** with clear boundaries
- **Component Export** for cross-module usage

### **Reactive Services** - State-Aware Infrastructure
- **Vue Reactivity** integrated into service layer
- **Computed Properties** for derived state
- **Watchers** for side-effect management
- **Event-Driven Communication** between services

## Development Workflow

### **Hot Module Replacement**
```bash
npm run dev  # Start development with HMR
```

### **Production Build**
```bash
npm run build    # TypeScript check + Vite build
npm run preview  # Preview production build locally
```

### **Electron Development**
```bash
npm run electron:dev    # Concurrent Vite + Electron
npm run electron:build  # Package desktop application
```

## See Also

- **[[getting-started|Getting Started Guide]]** - Setup and development instructions
- **[[../01-architecture/index|Architecture Overview]]** - System design patterns  
- **[[../04-development/coding-standards|Coding Standards]]** - Development guidelines
- **[[../02-modules/index|Module System]]** - Plugin architecture documentation

---

**Tags:** #technology #stack #vue #typescript #nostr #lightning  
**Last Updated:** 2025-09-06  
**Author:** Development Team