web-app/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Development

• npm run dev - Start development server with Vite (includes --host flag)
• npm run build - Build for production (includes TypeScript check with vue-tsc -b)
• npm run preview - Preview production build locally
• npm run analyze - Build with bundle analysis (opens visualization)

Electron Development

• npm run electron:dev - Run both Vite dev server and Electron concurrently
• npm run electron:build - Full build and package for Electron
• npm run start - Start Electron using Forge
• npm run package - Package Electron app with Forge
• npm run make - Create distributables with Electron Forge

Architecture Overview

This is a modular Vue 3 + TypeScript + Vite application with Electron support, featuring a Nostr protocol client and Lightning Network integration for events/ticketing.

Modular Architecture

The application uses a plugin-based modular architecture with dependency injection for service management:

Core Modules:

• Base Module (src/modules/base/) - Core infrastructure (Nostr, Auth, PWA)
• Nostr Feed Module (src/modules/nostr-feed/) - Social feed functionality
• Chat Module (src/modules/chat/) - Encrypted Nostr chat
• Events Module (src/modules/events/) - Event ticketing with Lightning payments
• Market Module (src/modules/market/) - Nostr marketplace functionality

Module Configuration:

• Modules are configured in src/app.config.ts
• Each module can be enabled/disabled and configured independently
• Modules have dependencies (e.g., all modules depend on 'base')

Plugin Manager:

• src/core/plugin-manager.ts handles module lifecycle
• Registers, installs, and manages module dependencies
• Handles route registration from modules

Dependency Injection Pattern

CRITICAL: Always use the dependency injection pattern for accessing shared services:

Service Registration (Base Module):

// src/modules/base/index.ts
import { container, SERVICE_TOKENS } from '@/core/di-container'

container.provide(SERVICE_TOKENS.RELAY_HUB, relayHub)
container.provide(SERVICE_TOKENS.AUTH_SERVICE, auth)

Service Consumption (Other Modules):

// In any module's composables or services
import { injectService, SERVICE_TOKENS } from '@/core/di-container'

const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)
const authService = injectService(SERVICE_TOKENS.AUTH_SERVICE)

❌ NEVER do this:

// DON'T import services directly - breaks modular architecture
import { relayHubComposable } from '@/composables/useRelayHub'

✅ Always do this:

// DO use dependency injection for loose coupling
const relayHub = injectService(SERVICE_TOKENS.RELAY_HUB)

Available Services:

• SERVICE_TOKENS.RELAY_HUB - Centralized Nostr relay management
• SERVICE_TOKENS.AUTH_SERVICE - Authentication services
• SERVICE_TOKENS.VISIBILITY_SERVICE - App visibility and connection management

Core Stack:

• Vue 3 with Composition API (<script setup> style)
• TypeScript throughout
• Vite build system with PWA support
• Electron for desktop app packaging
• Pinia for state management
• Vue Router for navigation
• TailwindCSS v4 with Shadcn/ui components
• Vue-i18n for internationalization

Key Features:

• Nostr protocol client for decentralized social networking
• Lightning Network integration for event ticketing
• PWA capabilities with service worker
• Theme switching and language switching
• Real-time connection status monitoring

Directory Structure:

• src/components/ - Vue components organized by feature
  • ui/ - Shadcn/ui component library
  • nostr/ - Nostr-specific components
  • events/ - Event/ticketing components
  • layout/ - App layout components
• src/composables/ - Vue composables for reusable logic
• src/stores/ - Pinia stores for state management
• src/lib/ - Core business logic
  • nostr/ - Nostr client implementation
  • api/ - API integrations
  • types/ - TypeScript type definitions
• src/pages/ - Route pages
• electron/ - Electron main process code

Nostr Integration: The app connects to Nostr relays using a custom NostrClient class built on nostr-tools. Key files:

• src/lib/nostr/client.ts - Core Nostr client implementation
• src/composables/useNostr.ts - Vue composable for Nostr connection management
• src/stores/nostr.ts - Pinia store for Nostr state

Development Guidelines

Modular Architecture Patterns

Module Structure:

src/modules/[module-name]/
├── index.ts                 # Module plugin definition
├── components/              # Module-specific components
├── composables/             # Module composables
├── services/               # Module services
├── stores/                 # Module-specific stores
├── types/                  # Module type definitions
└── views/                  # Module pages/views

Module Plugin Pattern:

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?: { config?: MyModuleConfig }) {
    // Module installation logic
    // Register components, initialize services, etc.
  },
  
  routes: [/* module routes */],
  components: {/* exported components */},
  composables: {/* exported composables */}
}

Service Integration:

• All modules MUST use dependency injection for shared services
• NEVER import services directly across module boundaries
• Base module provides core infrastructure services
• Modules can register their own services in the DI container

⚠️ CRITICAL - WebSocket Connection Management:

• ALWAYS integrate with VisibilityService for any module that uses WebSocket connections
• All services extending BaseService have automatic access to this.visibilityService
• Register visibility callbacks during service initialization: this.visibilityService.registerService(name, onResume, onPause)
• Implement proper connection recovery in onResume() handler (check health, reconnect if needed, restore subscriptions)
• Implement battery-conscious pausing in onPause() handler (stop heartbeats, queue operations)
• Mobile browsers suspend WebSocket connections when app loses visibility - visibility management is essential for reliable real-time features
• See docs/VisibilityService.md and docs/VisibilityService-Integration.md for comprehensive integration guides
• Future modules will likely ALL depend on WebSocket connections - plan for visibility management from the start

Centralized Infrastructure

Nostr Relay Management:

• Single RelayHub manages all Nostr connections
• All modules use the same relay configuration from VITE_NOSTR_RELAYS
• No module should create separate relay connections

Authentication:

• Centralized auth service handles all authentication
• Modules access auth state through dependency injection
• Router guards use the shared auth service

Configuration:

• Environment variables prefixed with VITE_
• Module configs in src/app.config.ts
• Centralized config parsing and validation

Code Conventions:

• Use TypeScript interfaces over types for extendability
• Prefer functional and declarative patterns over classes
• Use Vue Composition API with <script setup> syntax
• Follow naming convention: lowercase-with-dashes for directories
• Leverage VueUse functions for enhanced reactivity
• Implement lazy loading for non-critical components
• Optimize images using WebP format with lazy loading
• ALWAYS use dependency injection for cross-module service access

Build Configuration:

• Vite config includes PWA, image optimization, and bundle analysis
• Manual chunking strategy for vendor libraries (vue-vendor, ui-vendor, shadcn)
• Electron Forge configured for cross-platform packaging
• TailwindCSS v4 integration via Vite plugin

Environment:

• Nostr relay configuration via VITE_NOSTR_RELAYS environment variable
• PWA manifest configured for standalone app experience
• Service worker with automatic updates every hour