Agent Handbook

# Agent Handbook

Reference for coding agents working on the Pokemon Soullink Tracker.

## Project Overview

- React 19 + TypeScript single-page app built with Vite.
- Main entry points are `index.tsx` and `src/App.tsx`.
- The app uses Firebase Authentication and Firebase Realtime Database.
- Core product flow:
  - users sign in
  - users create or open trackers
  - trackers manage team, box, graveyard, rules, level caps, rival caps, fossils, and run stats
  - owners can invite members or guests and optionally expose trackers publicly in read-only mode

## Key Directories

- `src/App.tsx`: routing, auth/bootstrap, tracker lifecycle, modal orchestration, and most application state wiring
- `src/components/`: UI components and modal flows
- `src/services/`: Firebase access, search helpers, sprite resolution, emulator seed logic, and tracker/ruleset operations
- `src/data/`: static and generated data such as game versions, rulesets, Pokemon names, type data, and evolutions
- `src/locales/`: translation dictionaries for German and English
- `public/`: static images, fonts, sprite assets, and the service worker
- `types.ts`: shared domain types for trackers, rulesets, Pokemon links, stats, and user settings

## Runtime and Commands

- Install dependencies: `npm install`
- Start the app: `npm run dev`
- Start Firebase emulators: `npm run emulators`
- Create a production build: `npm run build`
- Preview the build: `npm run preview`
- Format the repo: `npm run prettier`
- Check formatting: `npm run prettier:check`
- Regenerate Pokemon datasets from PokeAPI: `npm run generate-pokemon`

## Environment Notes

- Local development is expected to use Firebase emulators.
- Copy `.env.example` to `.env` for local work.
- Production builds require the full set of `VITE_FIREBASE_*` variables.
- Firebase emulator wiring lives in `src/firebaseConfig.ts`.
- The app validates missing production Firebase config at runtime when emulator mode is disabled.

## Data Model

- Tracker metadata is stored under `trackers/{trackerId}/meta`.
- Tracker state is stored under `trackers/{trackerId}/state`.
- User-to-tracker membership lookups live under `userTrackers/{userId}`.
- User profiles live under `users/{userId}`.
- Email lookup records live under `userEmails/{encodedEmail}`.
- Custom rulesets live under `rulesets/{userId}/{rulesetId}`.

When changing tracker shape, update both runtime sanitizing code and any default-state helpers. The main normalization logic currently lives in `src/services/init.ts` and `src/App.tsx`.

## Localization Rules

- The UI supports German and English.
- Prefer translation keys over inline user-facing strings.
- When adding or changing UI copy, update both `src/locales/de.ts` and `src/locales/en.ts`.
- Keep labels, button text, and validation messages aligned across both locales.

## Coding Conventions

- Prefer functional React components and typed props.
- Extend `types.ts` or local interfaces instead of introducing `any`.
- Use the `@/` alias for imports from the project root.
- Keep data-fetching and Firebase mutation logic in `src/services/` rather than inside UI components.
- Reuse existing helpers for sanitizing player names, rules, tags, and state shape.
- Preserve read-only behavior for public trackers and guest users.

## Product-Specific Guardrails

- Game version data in `src/data/game-versions.ts` drives badges, level caps, rival caps, and generation limits.
- Rulesets can be presets or user-owned custom entries; do not treat presets as editable.
- Tracker creation and membership management are implemented in `src/services/trackers.ts`.
- Ruleset persistence is implemented in `src/services/rulesets.ts`.
- Emulator seed logic exists to provide deterministic local demo data; avoid breaking that flow.
- Generated Pokemon datasets in `src/data/` should be regenerated by script when possible instead of edited manually.

## Validation Checklist

- Run `npm run build` after meaningful code changes.
- Run `npm run prettier:check` if formatting might be affected.