CLAUDE.md

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

Commands

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

Docker:

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)

Constants — APP_VERSION, CONDITIONS array, defaults
Firebase config — reads REACT_APP_FIREBASE_* env vars
Firestore path helpers — getPath object
Utility functions — generateId(), rollD20(), sort helpers
Custom hooks — useFirestoreDocument, useFirestoreCollection
Reusable UI — Modal, ConfirmationModal, LoadingSpinner, ErrorDisplay
Feature components — forms, managers, controls (see below)
AdminView (~line 1942) — root DM component
DisplayView (~line 2186) — root player component
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

3.2 KiB Raw Blame History