# CLAUDE.md

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

## Commands

```bash
npm start          # Dev server at http://localhost:3000
npm run build      # Production build
npm test           # Run tests (no test files currently exist)
```

Docker:
```bash
docker build -t ttrpg-initiative-tracker .
docker run -p 8080:80 --rm --name ttrpg-tracker-app ttrpg-initiative-tracker
```

The Dockerfile uses `NODE_OPTIONS=--openssl-legacy-provider npm run build` to work around an OpenSSL compatibility issue between Node 18 and react-scripts 5.

## Architecture

Single-page React app (Create React App) for DMs to manage TTRPG combat encounters with a real-time player display. The entire application — all components, hooks, Firebase init, and routing — lives in **`src/App.js`** (~2500 lines).

**Key dependencies:** React 18, Firebase SDK v10 (Firestore + anonymous auth), Tailwind CSS v3, lucide-react icons.

### Two App Modes (query-param routing)

- Default URL → `AdminView`: full DM interface (campaign/encounter/participant management)
- `?playerView=true` or `/display` → `DisplayView`: read-only player-facing view for a second monitor

### Firebase / Firestore

All app state lives in Firestore under `artifacts/{APP_ID}/public/data/`:
- `campaigns/` — campaign documents
- `campaigns/{id}/encounters/` — sub-collections with a `participants` array per encounter
- `activeDisplay/status` — single doc controlling what the player display shows

`APP_ID` defaults to `"ttrpg-initiative-tracker-default"` and can be overridden via `REACT_APP_TRACKER_APP_ID`.

All users authenticate anonymously (Firebase Anonymous Auth). If `window.__initial_auth_token` is set, a custom token is used instead.

Real-time updates use two custom hooks in App.js: `useFirestoreDocument(docPath)` and `useFirestoreCollection(collectionPath)`, both backed by `onSnapshot`.

### App.js Sections (in order)

1. Constants — `APP_VERSION`, `CONDITIONS` array, defaults
2. Firebase config — reads `REACT_APP_FIREBASE_*` env vars
3. Firestore path helpers — `getPath` object
4. Utility functions — `generateId()`, `rollD20()`, sort helpers
5. Custom hooks — `useFirestoreDocument`, `useFirestoreCollection`
6. Reusable UI — `Modal`, `ConfirmationModal`, `LoadingSpinner`, `ErrorDisplay`
7. Feature components — forms, managers, controls (see below)
8. `AdminView` (~line 1942) — root DM component
9. `DisplayView` (~line 2186) — root player component
10. `App` (~line 2426) — auth + routing

Major feature components: `CreateCampaignForm`, `CreateEncounterForm`, `EditParticipantModal`, `CharacterManager`, `ParticipantManager`, `InitiativeControls`, `EncounterManager`.

### Styling

Tailwind CSS with two custom font families configured in `tailwind.config.js`:
- `font-cinzel` — Cinzel (serif, used for headings)
- `font-garamond` — Alegreya Sans (default body font)

### Environment Variables

Copy `env.example` to `.env.local` and fill in Firebase credentials:

```
REACT_APP_FIREBASE_API_KEY
REACT_APP_FIREBASE_AUTH_DOMAIN
REACT_APP_FIREBASE_PROJECT_ID
REACT_APP_FIREBASE_STORAGE_BUCKET
REACT_APP_FIREBASE_MESSAGING_SENDER_ID
REACT_APP_FIREBASE_APP_ID
REACT_APP_TRACKER_APP_ID   # optional, Firestore namespace
```