# CLAUDE.md

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

## Project Overview

Smesh is a React/TypeScript Nostr client for exploring relay feeds. It's a PWA built with Vite, using TailwindCSS for styling and Radix UI/shadcn components.

## Development Commands

```bash
npm install       # Install dependencies
npm run dev       # Start dev server (Vite, accessible on local network)
npm run dev:8080  # Start dev server on 0.0.0.0:8080 with hot-reload
./hotrefresh      # Kill and restart the dev server on port 8080
npm run build     # TypeScript check + Vite build
npm run lint      # Run ESLint
npm run format    # Run Prettier
npm run preview   # Preview production build
```

Docker: `docker compose up --build -d` (serves on localhost:8089)

## Architecture

### Directory Structure

- `src/pages/primary/` - Main tab pages (home, explore, notifications, settings, etc.)
- `src/pages/secondary/` - Detail/modal pages (note view, user profile, relay details)
- `src/providers/` - React Context providers for state management
- `src/services/` - Business logic and external integrations
- `src/components/` - Reusable UI components (with `ui/` subdirectory for base components)
- `src/lib/` - Utility functions
- `src/hooks/` - Custom React hooks
- `src/routes/` - Route definitions (primary.tsx and secondary.tsx)
- `src/i18n/` - Internationalization with i18next

### State Management

Uses React Context API with 17+ nested providers in `App.tsx`. Key providers:
- `NostrProvider` - Core authentication and signing (supports nsec, NIP-07, NIP-46 bunker, ncryptsec, npub view-only)
- `FeedProvider` - Active feed state (following, relays, pinned)
- `FavoriteRelaysProvider` - User's relay sets
- `FollowListProvider`, `MuteListProvider` - Social graph

Provider pattern:
```typescript
const Context = createContext<TContext | undefined>(undefined)
export const useMyFeature = () => {
  const context = useContext(Context)
  if (!context) throw new Error('Must be within provider')
  return context
}
```

### Routing

Custom stack-based navigation in `PageManager.tsx`:
- Primary pages: Main tabs rendered in left column (desktop) or full screen (mobile)
- Secondary pages: Detail views rendered in right column or as overlay stack
- Uses `path-to-regexp` for URL matching
- `usePrimaryPage()` and `useSecondaryPage()` hooks for navigation

### Nostr Integration

- `ClientService` (`src/services/client.service.ts`) - Singleton wrapping `nostr-tools` SimplePool
- Event caching with DataLoader and LRU cache
- User search with FlexSearch index
- IndexedDB storage for events (`indexed-db.service.ts`)
- localStorage for preferences (`local-storage.service.ts`)

Key types in `src/types/index.d.ts`:
- `TProfile`, `TRelayList`, `TDraftEvent`, `ISigner`

### UI Components

- Base components: Radix UI primitives in `src/components/ui/`
- Rich text editor: Tiptap in `src/components/PostEditor/`
- Note display: `src/components/Note/NoteCard.tsx`

## Key Patterns

### Path Alias
`@/` maps to `src/` (configured in tsconfig.json and vite.config.ts)

### Page Components
Pages use `forwardRef` to expose `scrollToTop` method:
```typescript
const MyPage = forwardRef<TPageRef>((props, ref) => {
  useImperativeHandle(ref, () => ({ scrollToTop: (behavior) => ... }))
})
```

### Event Constants
Nostr event kinds in `src/constants.ts`:
- Standard kinds from `nostr-tools`
- Extended kinds in `ExtendedKind` (polls, pictures, voice notes, etc.)
- Regex patterns for content parsing (URLs, mentions, hashtags, etc.)

## Important Files

- `src/App.tsx` - Provider nesting order matters
- `src/PageManager.tsx` - Navigation and layout logic
- `src/constants.ts` - Global constants, relay URLs, storage keys
- `src/lib/event.ts` - Event parsing utilities