Create comprehensive Obsidian-style documentation structure

- Reorganize all markdown documentation into structured docs/ folder - Create 7 main documentation categories (00-overview through 06-deployment) - Add comprehensive index files for each category with cross-linking - Implement Obsidian-compatible [[link]] syntax throughout - Move legacy/deprecated documentation to archive folder - Establish documentation standards and maintenance guidelines - Provide complete coverage of modular architecture, services, and deployment - Enable better navigation and discoverability for developers and contributors 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-06 14:31:27 +02:00 · 2025-09-06 14:31:27 +02:00 · cdf099e45f
commit cdf099e45f
parent 46856134ef
29 changed files with 3733 additions and 0 deletions
--- a/docs/00-overview/index.md
+++ b/docs/00-overview/index.md
@ -0,0 +1,136 @@
+# 📖 Overview
+
+> **Welcome to the Ario Web Application** - A modular Vue 3 + TypeScript application with Nostr protocol integration and Lightning Network payments.
+
+## Table of Contents
+
+- [[#What is Ario?]]
+- [[#Key Features]]
+- [[#Technology Stack]]
+- [[#Quick Start]]
+- [[#Documentation Navigation]]
+
+## What is Ario?
+
+Ario is a decentralized social and marketplace application built on the Nostr protocol with Lightning Network integration. It provides users with:
+
+- **Decentralized Social Networking** - Connect through the Nostr protocol
+- **Lightning Payments** - Instant, low-fee Bitcoin payments
+- **Event Ticketing** - Create and manage events with Lightning payments
+- **Encrypted Messaging** - Private, secure communications
+- **Marketplace Functionality** - Buy and sell goods using Lightning Network
+
+## Key Features
+
+### 🔒 **Privacy-First Architecture**
+- No central servers storing user data
+- Nostr protocol ensures user sovereignty
+- Client-side key management with secure encryption
+
+### ⚡ **Lightning Network Integration**
+- Instant Bitcoin payments for events and marketplace
+- Low transaction fees
+- Invoice generation and payment tracking
+
+### 🏗️ **Modular Architecture**
+- Plugin-based module system
+- Dependency injection for service management
+- Clean separation of concerns
+- Easy to extend and maintain
+
+### 📱 **Multi-Platform Support**
+- Progressive Web App (PWA) capabilities
+- Electron desktop application
+- Responsive design for mobile and desktop
+
+### 🌍 **Internationalization**
+- Multi-language support with Vue-i18n
+- Theme switching (light/dark modes)
+- Accessibility-focused design
+
+## Technology Stack
+
+### Frontend Core
+- **Vue 3** with Composition API and `<script setup>`
+- **TypeScript** throughout for type safety
+- **Vite** for fast development and optimized builds
+- **TailwindCSS v4** with Shadcn/ui components
+
+### State Management & Routing
+- **Pinia** for reactive state management
+- **Vue Router** for navigation
+- **Vue-i18n** for internationalization
+
+### Nostr & Lightning
+- **Nostr-tools** for protocol implementation
+- **WebLN** for Lightning Network browser integration
+- **QR Code generation** for Lightning invoices
+
+### Desktop & PWA
+- **Electron** for desktop application packaging
+- **Vite PWA Plugin** for Progressive Web App features
+- **Service Worker** for offline capabilities
+
+## Quick Start
+
+### Prerequisites
+- Node.js 18+ and npm
+- Basic knowledge of Vue 3 and TypeScript
+
+### Development Setup
+```bash
+# Navigate to the web app directory
+cd web-app/
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# For Electron development
+npm run electron:dev
+```
+
+### Environment Configuration
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Configure Nostr relays
+VITE_NOSTR_RELAYS='["wss://relay1.example.com","wss://relay2.example.com"]'
+
+# Configure admin pubkeys for announcements
+VITE_ADMIN_PUBKEYS='["hexadecimal_pubkey_1","hexadecimal_pubkey_2"]'
+```
+
+## Documentation Navigation
+
+### Essential Reading (Start Here)
+1. **[[getting-started|🚀 Getting Started]]** - Detailed setup instructions
+2. **[[project-goals|🎯 Project Goals]]** - Vision and objectives
+3. **[[tech-stack|🛠️ Technology Stack]]** - Detailed technology overview
+
+### Architecture & Development
+- **[[../01-architecture/index|🏗️ Architecture Overview]]** - System design patterns
+- **[[../04-development/index|💻 Development Guide]]** - Coding standards and workflows
+
+### Feature Modules
+- **[[../02-modules/index|📦 Modules Overview]]** - Feature module documentation
+- **[[../03-core-services/index|⚙️ Core Services]]** - Shared infrastructure services
+
+### Integration & Deployment
+- **[[../05-api-reference/index|📡 API Reference]]** - External integrations
+- **[[../06-deployment/index|🚀 Deployment]]** - Production deployment guide
+
+## See Also
+
+- **[[../01-architecture/modular-design|Modular Architecture]]** - Understanding the plugin system
+- **[[../04-development/coding-standards|Coding Standards]]** - Code quality guidelines
+- **[[../02-modules/base-module/index|Base Module]]** - Core infrastructure documentation
+
+---
+
+**Tags:** #overview #introduction #getting-started  
+**Last Updated:** 2025-09-06  
+**Author:** Development Team
--- a/docs/00-overview/project-goals.md
+++ b/docs/00-overview/project-goals.md
@ -0,0 +1,137 @@
+# 🎯 Project Goals
+
+> **Ario's mission** - Building a decentralized, user-sovereign platform for social interaction, commerce, and events powered by Bitcoin and Nostr.
+
+## Table of Contents
+
+- [[#Vision]]
+- [[#Core Objectives]]
+- [[#Technical Goals]]
+- [[#User Experience Goals]]
+- [[#Ecosystem Goals]]
+
+## Vision
+
+Ario aims to create a **decentralized alternative** to traditional social media and marketplace platforms by leveraging the Nostr protocol and Lightning Network. Our vision is a world where users have complete control over their data, identity, and financial transactions.
+
+### Key Principles
+- **User Sovereignty** - Users own their data and identity
+- **Censorship Resistance** - No central authority can silence users  
+- **Financial Freedom** - Direct peer-to-peer value exchange
+- **Open Source** - Transparent, auditable, and collaborative development
+
+## Core Objectives
+
+### 1. **Decentralized Social Networking**
+- Enable users to connect without intermediaries
+- Provide familiar social media features on decentralized infrastructure  
+- Support rich content sharing (text, images, events)
+- Enable real-time communication through Nostr relays
+
+### 2. **Lightning-Powered Commerce**
+- Facilitate instant, low-fee Bitcoin payments
+- Enable event ticketing with Lightning invoices
+- Support marketplace transactions
+- Provide seamless payment UX comparable to traditional payment methods
+
+### 3. **Privacy and Security**
+- Client-side key management with secure encryption
+- No central storage of sensitive user data
+- Optional anonymity and pseudonymity support
+- End-to-end encrypted messaging capabilities
+
+### 4. **User-Friendly Experience**
+- Intuitive interface that doesn't compromise on decentralization
+- Progressive Web App with offline capabilities
+- Mobile-first responsive design
+- Multi-language and accessibility support
+
+## Technical Goals
+
+### Architecture Excellence
+- **Modular Design** - Plugin-based architecture for easy extension
+- **Type Safety** - TypeScript throughout for reliability
+- **Performance** - Optimized builds and lazy loading
+- **Maintainability** - Clean code patterns and comprehensive documentation
+
+### Protocol Implementation  
+- **Nostr Compliance** - Full implementation of relevant NIPs (Nostr Implementation Possibilities)
+- **Lightning Integration** - WebLN support and invoice management
+- **Relay Management** - Intelligent relay selection and failover
+- **Real-time Updates** - Efficient event subscription and filtering
+
+### Developer Experience
+- **Clear Abstractions** - Well-defined service interfaces
+- **Dependency Injection** - Loose coupling between modules
+- **Comprehensive Testing** - Unit and integration test coverage
+- **Documentation** - Thorough guides for contributors
+
+## User Experience Goals
+
+### Onboarding Experience
+- **Simple Setup** - Easy key generation or import process
+- **Educational Content** - Help users understand Nostr and Lightning
+- **Progressive Disclosure** - Advanced features revealed as users are ready
+- **Recovery Options** - Secure backup and recovery mechanisms
+
+### Daily Usage
+- **Fast Performance** - Sub-second response times for common actions
+- **Reliable Connectivity** - Robust relay connection management
+- **Intuitive Navigation** - Clear information architecture
+- **Rich Interactions** - Engaging social and commerce features
+
+### Advanced Features
+- **Power User Tools** - Advanced relay management and filtering
+- **Privacy Controls** - Granular privacy and visibility settings
+- **Integration APIs** - Support for third-party integrations
+- **Customization** - Theming and layout preferences
+
+## Ecosystem Goals
+
+### Developer Ecosystem
+- **Open Source Community** - Encourage contributions and forks
+- **Plugin Architecture** - Enable third-party module development  
+- **API Documentation** - Clear integration guides for developers
+- **Development Tools** - Debugging and development utilities
+
+### Network Effects
+- **Relay Diversity** - Support a healthy, distributed relay network
+- **Interoperability** - Compatibility with other Nostr clients
+- **Standard Compliance** - Active participation in NIP development
+- **Community Building** - Foster vibrant user communities
+
+### Economic Sustainability
+- **Lightning Adoption** - Drive Lightning Network usage growth
+- **Value Creation** - Enable new economic models through programmable money
+- **Fee Optimization** - Minimize transaction costs for users
+- **Revenue Sharing** - Fair compensation for relay operators and developers
+
+## Success Metrics
+
+### User Adoption
+- Monthly active users across web and desktop platforms
+- User retention rates and engagement metrics
+- Geographic distribution and diversity
+
+### Technical Performance  
+- Application load times and responsiveness
+- Relay connection success rates and latency
+- Payment success rates and confirmation times
+
+### Ecosystem Health
+- Number of connected relays and geographic distribution
+- Integration with other Nostr clients and services
+- Developer contributions and community participation
+
+## See Also
+
+- **[[getting-started|Getting Started Guide]]** - Begin your journey with Ario
+- **[[tech-stack|Technology Stack]]** - Technical implementation details
+- **[[../01-architecture/index|Architecture Overview]]** - System design principles
+- **[[../04-development/index|Development Guide]]** - Contributing to Ario
+
+---
+
+**Tags:** #vision #goals #strategy #roadmap  
+**Last Updated:** 2025-09-06  
+**Author:** Development Team
--- a/docs/00-overview/tech-stack.md
+++ b/docs/00-overview/tech-stack.md
@ -0,0 +1,241 @@
+# 🛠️ 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