From 63de0839096c1ca5a311a8108e7676e23bb2fafd Mon Sep 17 00:00:00 2001
From: padreug <padreug@aiolabs.dev>
Date: Fri, 5 Sep 2025 01:14:42 +0200
Subject: [PATCH] Enhance CLAUDE.md with modular architecture documentation

- Update architecture overview to emphasize the modular structure of the application.
- Introduce detailed sections on core modules, module configuration, and the plugin manager.
- Outline the dependency injection pattern for service management across modules.
- Add development guidelines for module structure, plugin patterns, and service integration.
- Emphasize the importance of using dependency injection for cross-module service access.
---
 CLAUDE.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 120 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7c4b873..7905a21 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,7 +19,67 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Architecture Overview
 
-This is a Vue 3 + TypeScript + Vite application with Electron support, featuring a Nostr protocol client and Lightning Network integration for events/ticketing.
+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):**
+```typescript
+// 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):**
+```typescript
+// 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:**
+```typescript
+// DON'T import services directly - breaks modular architecture
+import { relayHubComposable } from '@/composables/useRelayHub'
+```
+
+**✅ Always do this:**
+```typescript
+// 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.NOSTR_CLIENT_HUB` - Nostr client services  
+- `SERVICE_TOKENS.AUTH_SERVICE` - Authentication services
 
 **Core Stack:**
 - Vue 3 with Composition API (`<script setup>` style)
@@ -59,7 +119,64 @@ The app connects to Nostr relays using a custom NostrClient class built on nostr
 - `src/composables/useNostr.ts` - Vue composable for Nostr connection management
 - `src/stores/nostr.ts` - Pinia store for Nostr state
 
-**Code Conventions:**
+## 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:**
+```typescript
+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
+
+### **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
@@ -67,6 +184,7 @@ The app connects to Nostr relays using a custom NostrClient class built on nostr
 - 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