# CLAUDE.md

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

## Development Commands

- **Development server**: `bun run dev` - Starts Vite dev server on http://localhost:5173
- **Build**: `bun run build` - TypeScript compilation followed by Vite production build
- **Linting**: `bun run lint` - Run ESLint on all files
- **Preview build**: `bun run preview` - Preview production build locally
- **Type checking**: `tsc -b` - Run TypeScript compiler to check types

## Architecture

This is a React TypeScript frontend for an Urbit application called Nostrill, which appears to integrate Nostr (decentralized social protocol) with Urbit (personal server).

### Key Technologies
- **React 19** with TypeScript
- **Vite** for build tooling
- **Zustand** for global state management
- **TanStack Query** for server state and data fetching
- **Wouter** for routing
- **Urbit API** integration via custom packages in parent directories

### Project Structure

```
src/
├── components/     # UI components organized by feature
│   ├── composer/   # Post composition UI
│   ├── feed/       # Feed display components
│   ├── layout/     # Layout components (Sidebar, etc.)
│   ├── modals/     # Modal dialogs
│   └── post/       # Post display components and wrappers
├── logic/          # Business logic and utilities
│   ├── api.ts      # Urbit connection setup
│   ├── nostrill.ts # Nostrill-specific logic
│   └── requests/   # API request handlers
├── pages/          # Route components (Feed, User, Settings)
├── state/          # Zustand store (state.ts)
├── styles/         # Styling and theming
├── types/          # TypeScript type definitions
└── Router.tsx      # Main routing configuration
```

### State Management

The application uses Zustand for state management (`src/state/state.ts`):
- Manages Urbit connection via `IO` class
- Stores Nostr events, user profiles, relay data
- Handles following/followers relationships
- Manages UI state (modals, composer data)

### Urbit Integration

- Connection established via `src/logic/api.ts`
- Uses Urbit Airlock/SSE for real-time updates
- Interacts with the `nostrill` desk on the Urbit ship
- Local packages used from parent directories:
  - `urbit-api`: HTTP API client
  - `urbit-ob`: Urbit ID utilities
  - `urbit-sigils`: Visual ship identifiers

### Path Aliases

The project uses `@` alias for `src/` directory (configured in vite.config.ts).

### Key Data Flows

1. **Initialization**: App.tsx → state.init() → api.start() → Urbit connection
2. **State Updates**: Urbit SSE → IO subscriptions → Zustand store updates
3. **User Actions**: Components → IO methods → Urbit pokes/scries → State updates

## Future Feature Ideas

### 1. Real-time Notifications System
- Toast notifications for new follows, mentions, access requests
- Bell icon with notification count in sidebar
- Notification center/inbox with activity history
- Sound/desktop notifications
- Mark as read/unread functionality

### 2. Advanced Post Composer
- Rich text editor with markdown support
- Image/media upload and preview
- Draft saving (auto-save as you type)
- Post scheduling for later
- Character count and formatting preview
- Emoji picker integration
- @mentions with autocomplete

### 3. Search & Discovery
- Global search for posts, users, hashtags
- Trending topics/hashtags
- User discovery with suggested follows
- Advanced filters (date range, user, content type)
- Search history and saved searches

### 4. Bookmarking System
- Save posts for later reading
- Organize bookmarks into collections/folders
- Search through saved posts
- Export bookmarks
- Private notes on bookmarks

### 5. Post Analytics Dashboard
- View engagement metrics on your posts
- Follower growth over time graphs
- Most popular posts
- Activity heatmap
- Engagement rate tracking
- Best posting times analysis

### 6. Direct Messaging
- Private messaging between users
- Encrypted DMs via Nostr/Urbit protocols
- Message threads and history
- File sharing in DMs
- Read receipts
- Typing indicators

### 7. Additional Features to Consider
- User groups/communities
- Content moderation tools
- Multi-account support
- Import/export data
- PWA support for mobile
- Keyboard shortcuts
- Custom themes creator
- Language translations