# CLAUDE.md

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

## Essential Commands

### Development
```bash
yarn dev          # Start Vite development server on port 5173
yarn preview      # Preview production build locally
```

### Build & Deploy
```bash
yarn build        # Create production build with Vite
make build        # Build Docker image (tuxpa.in/a/lto:v0.0.2)
make push         # Push Docker image to registry
```

### Code Quality
```bash
yarn lint         # Check code with Biome
yarn lint:fix     # Auto-fix linting issues
yarn format       # Format code with Biome
```

## Architecture Overview

This is a React-based inventory management system for the game "Trickster Online" via the lifeto.co platform.

### Key Technologies
- **React 19** with TypeScript
- **Vite** for bundling and dev server
- **Jotai** for atomic state management
- **TanStack Query** for server state and caching
- **Tailwind CSS** for styling
- **Axios** for HTTP requests

### Core Architecture

1. **State Management Pattern**:
   - Jotai atoms in `src/state/atoms.ts` handle all application state
   - Uses `atomWithQuery` for server data integration
   - Persistent storage via `atomWithStorage` with superjson serialization
   - Actions are implemented as write-only atoms (e.g., `doLoginAtom`, `orderManagerAtom`)

2. **API Integration**:
   - All API calls go through `LTOApi` interface (`src/lib/lifeto/api.ts`)
   - Token-based authentication via `TokenSession`
   - Development: Vite proxy to `https://beta.lifeto.co`
   - Production: Caddy reverse proxy configuration

3. **Component Structure**:
   - Entry: `src/index.tsx` → `App.tsx`
   - Main sections: Login, Character Selection, Inventory Management
   - Components follow atomic design with clear separation of concerns

4. **Business Logic**:
   - Domain models in `src/lib/trickster.ts` (Character, Item, Inventory)
   - Order management via `OrderManager` class for item transfers
   - Item filtering uses Fuse.js for fuzzy search

5. **Data Flow**:
   ```
   User Action → Component → Jotai Action Atom → API Call → 
   Server Response → Query Cache → Atom Update → UI Re-render
   ```

### Development Notes

- The app uses a proxy setup to avoid CORS issues with the lifeto.co API
- All API responses are strongly typed with TypeScript interfaces
- State persistence allows users to maintain their session and preferences
- The inventory system supports multi-character management with bulk operations