mkstackwithwelshman/README.md

# MKStack with Welshman

Template for building Nostr client applications with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify - enhanced with Welshman for intelligent relay management.

## Overview

This is an enhanced version of the MKStack template that replaces the basic `NPool` implementation with `NWelshman` - a more sophisticated relay pool manager that provides intelligent routing, quality scoring, and specialized relay selection.

## Key Differences from Base MKStack

### 1. Enhanced Relay Management

**Base MKStack (NPool):**
- Simple relay connection using `NRelay1`
- All queries go to a single configured relay
- Basic round-robin publishing to preset relays
- No distinction between relay types or capabilities

**This Template (NWelshman):**
- Intelligent relay routing with quality scoring
- Specialized relay selection based on query type:
  - **Indexer relays** for metadata (kinds 0, 3, 10002)
  - **Search relays** for NIP-50 full-text search
  - **Static relays** for general queries
- Quality-based relay prioritization
- Configurable redundancy and connection limits

### 2. Router Configuration

The `NostrProvider` now implements a sophisticated Router class that provides:

```typescript
// Relay selection based on capability
getIndexerRelays()    // Returns relays optimized for metadata
getSearchRelays()      // Returns NIP-50 compatible search relays
getStaticRelays()      // Returns general-purpose relays

// Quality assessment
getRelayQuality(url)   // Returns 0-1 quality score per relay

// Connection management
getRedundancy()        // Number of relays to query (default: 2)
getLimit()            // Maximum relay connections (default: 5)
```

### 3. Performance Benefits

- **Reduced latency**: Queries are sent to relays best suited for the task
- **Better reliability**: Redundancy ensures queries succeed even if one relay fails
- **Optimized bandwidth**: Intelligent routing reduces unnecessary connections
- **Faster metadata lookups**: Dedicated indexer relays for profile data
- **Enhanced search**: NIP-50 aware relay selection for text search

## Dependencies

This template adds the following dependencies to base MKStack:

```json
{
  "@nostrify/welshman": "^0.35.0",
  "@welshman/util": "^0.4.2"
}
```

## Usage

The template maintains full compatibility with the base MKStack API. All existing hooks and components work without modification:

```tsx
// Works exactly the same as base MKStack
const { nostr } = useNostr();
const events = await nostr.query([{ kinds: [1], limit: 20 }]);
```

## Relay Configuration

The Router automatically categorizes relays based on their known capabilities:

### Known Indexer Relays
- `wss://relay.nostr.band`
- `wss://relay.damus.io`
- `wss://purplepag.es`

### Known Search Relays (NIP-50)
- `wss://relay.nostr.band`
- `wss://nostr.wine`
- `wss://search.nos.today`

### Quality Scoring
Relays are scored from 0.0 to 1.0 based on:
- User's configured relay: 1.0 (highest priority)
- Known high-quality relays: 0.8-0.9
- Preset relays: 0.7
- Unknown relays: 0.5 (lowest priority)

## Testing

The template includes comprehensive test coverage:

- **Unit tests** (`NostrProvider.test.tsx`): Mock-based testing of router configuration
- **Integration tests** (`NostrProvider.integration.test.tsx`): Real relay connection tests

Run tests with:
```bash
npm test
```

## Migration from Base MKStack

To migrate an existing MKStack project to use Welshman:

1. Install the new dependencies:
   ```bash
   npm install @nostrify/welshman @welshman/util
   ```

2. Replace the `NostrProvider` component with the Welshman version

3. No other code changes required - the API remains the same

## When to Use This Template

Choose this Welshman-enhanced template when you need:

- **High-performance Nostr apps** that benefit from intelligent relay routing
- **Apps with heavy metadata queries** (profile lookups, contact lists)
- **Search functionality** using NIP-50
- **Better reliability** through redundancy
- **Production-ready** relay management

Use the base MKStack template for:
- Simple prototypes or learning projects
- Apps that only need basic relay connectivity
- Minimal dependency requirements

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

## License

Same as MKStack base template.