79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# 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
|
|
```
|