# 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