<!-- FOR AI AGENTS - Human readability is a side effect, not a goal -->
<!-- Managed by agent: keep sections and order; edit content, not structure -->
<!-- Last updated: 2026-05-06 | Last verified: 2026-05-06 -->

# AGENTS.md

**tipsharks-client** — React Native mobile racing tips app (thoroughbred, harness, greyhound) with FastAPI + MongoDB backend.

**Precedence:** this file overrides root `AGENTS.md` for files in `tipsharks-client/`.

## Overview
Mobile app for browsing races, generating tips, and scheduling notifications across three racing types: thoroughbred, harness, and greyhound. Frontend is Expo/React Native with TypeScript. Backend is a single-file FastAPI service with MongoDB.

## Setup

### Frontend (React Native / Expo)
```bash
cd frontend
yarn install
yarn start          # Start Expo dev server
yarn android        # Run on Android
yarn ios            # Run on iOS
yarn web            # Run on web
yarn lint           # Run ESLint
```

**Dependencies**: Node.js, Yarn, Expo CLI
**Stack**: Expo 54, React 19, React Native 0.79, TypeScript 5.8

### Backend (FastAPI + MongoDB)
```bash
cd backend
pip install -r requirements.txt
# Set MONGO_URL and DB_NAME in .env
uvicorn server:app --reload
```

**Dependencies**: Python 3.12+, MongoDB
**Stack**: FastAPI 0.110, Motor (async MongoDB), Pydantic

## Commands
> Source: frontend/package.json + backend/requirements.txt

<!-- AGENTS-GENERATED:START commands -->
| Task | Command | ~Time |
|------|---------|-------|
| Install (frontend) | `cd frontend && yarn install` | ~30s |
| Dev (frontend) | `cd frontend && yarn start` | - |
| Android | `cd frontend && yarn android` | - |
| iOS | `cd frontend && yarn ios` | - |
| Web | `cd frontend && yarn web` | - |
| Lint (frontend) | `cd frontend && yarn lint` | ~5s |
| Install (backend) | `cd backend && pip install -r requirements.txt` | ~30s |
| Dev (backend) | `cd backend && uvicorn server:app --reload` | - |
| Format (backend) | `cd backend && black .` | ~5s |
| Lint (backend) | `cd backend && flake8 .` | ~5s |
| Typecheck (backend) | `cd backend && mypy server.py` | ~5s |
<!-- AGENTS-GENERATED:END commands -->

## File Map
<!-- AGENTS-GENERATED:START filemap -->
```
tipsharks-client/
├── frontend/                    # React Native / Expo app
│   ├── app/                     # Expo Router screens
│   │   ├── _layout.tsx          # Root layout
│   │   ├── (tabs)/              # Tab navigation screens
│   │   ├── race-picker.tsx      # Race selection screen
│   │   ├── schedule-builder.tsx # Notification scheduling
│   │   ├── tip-builder.tsx      # Tip generation screen
│   │   └── tip-result.tsx       # Tip results display
│   ├── src/
│   │   ├── components/          # Reusable UI components
│   │   ├── services/            # API client services
│   │   ├── store/               # Zustand state management
│   │   ├── types/               # TypeScript type definitions
│   │   └── utils/               # Shared utilities
│   ├── assets/                  # Images, fonts, icons
│   ├── scripts/                 # Utility scripts
│   ├── app.json                 # Expo configuration
│   ├── package.json             # Dependencies + scripts
│   ├── tsconfig.json            # TypeScript config
│   ├── eslint.config.js         # ESLint config
│   └── metro.config.js          # Metro bundler config
├── backend/
│   ├── server.py                # FastAPI app + all endpoints + mock data
│   ├── requirements.txt         # Python dependencies
│   └── .env                     # Environment variables (MONGO_URL, DB_NAME)
├── tests/                       # Test suite
│   └── __init__.py
├── backend_test.py              # Backend test script
└── test_result.md               # Test results
```
<!-- AGENTS-GENERATED:END filemap -->

## Code style

### Frontend
- TypeScript strict mode
- Expo lint rules (`eslint-config-expo`)
- Expo Router for file-based routing
- Zustand for state management
- React Query (`@tanstack/react-query`) for server state
- React Navigation for tab/bottom navigation
- Components in `src/components/`, screens in `app/`

### Backend
- FastAPI with Pydantic models for request/response validation
- Motor (async MongoDB driver) for database operations
- Single-file architecture (`server.py`) — all endpoints, models, and mock data in one file
- CORS enabled for all origins (development)
- Mock data generation for races, runners, and tips

## Security
- Never commit `.env` files (MongoDB credentials)
- Backend uses `MONGO_URL` and `DB_NAME` from environment
- CORS allows all origins — restrict in production
- No authentication currently implemented (single user: `default_user`)

## Checklist
Before committing:
- [ ] Frontend: `yarn lint` passes
- [ ] Backend: `black .` and `flake8 .` pass
- [ ] No hardcoded credentials in `.env`
- [ ] API endpoints have Pydantic models for validation

## Examples
<!-- AGENTS-GENERATED:START golden-samples -->
| For | Reference | Key patterns |
|-----|-----------|--------------|
| Screen | `app/*.tsx` | Expo Router, React Navigation |
| Component | `src/components/` | Reusable UI, props typing |
| Service | `src/services/` | Axios API client |
| Store | `src/store/` | Zustand state management |
| API endpoint | `backend/server.py` | FastAPI router, Pydantic models |
| Mock data | `backend/server.py` | Random generation, racing types |
<!-- AGENTS-GENERATED:END golden-samples -->

## When stuck
- Check `frontend/app.json` for Expo configuration
- Review `backend/server.py` for all API endpoints and data models
- Racing types: `thoroughbred`, `harness`, `greyhound` — each has unique tracks, names, and terminology
- Backend is single-file — all models, endpoints, and mock data in `server.py`
- Frontend uses Expo Router — screens are files in `app/` directory

## Key Architecture Notes
- **Three racing types**: thoroughbred (jockeys, weights), harness (drivers, sulky), greyhound (no rider, box draws)
- **Tip generation**: Probability-based model using form, barrier, weight factors
- **Bet types**: win, place, best_bet, quinella, exacta, trifecta
- **Notifications**: Scheduled tips with configurable lead times (5/15/30/60 min)
- **Backend state**: MongoDB collections for saved_tips, schedules, notifications, preferences