# CLAUDE.md - Codebase Documentation for Claude Code

This file helps Claude understand the Deathwatch Roller codebase and provide better assistance.

## Project Overview

**Deathwatch Roller** is a React-based web application for managing Deathwatch tabletop RPG sessions.

**Main Features:**
- Player management (CRUD operations for player accounts)
- Requisition shop (browse and purchase items with RP)
- Session tracking (track game sessions and progress)
- GM Kit (comprehensive Game Master tools)
- Bestiary (monster and enemy reference)
- Rules database (searchable rules and mechanics)

**Tech Stack:**
- Frontend: React + TypeScript
- Backend: Node.js + Express + TypeScript
- Database: SQLite
- Styling: CSS modules / Tailwind

## Architecture

```
dwroller/
├── backend/          # Express API server
├── frontend/         # React frontend (Vite)
├── data/            # Static data and assets
├── database/        # SQLite database and backups
└── docs/            # Documentation (see docs/)
```

## Key Files and Locations

### Backend
- `backend/server.js` - Express server entry point
- `backend/src/routes/` - API route handlers
- `backend/src/middleware/` - Authentication, validation middleware
- `backend/src/models/` - Data models
- `backend/src/controllers/` - Route controllers

### Frontend
- `frontend/src/components/` - React components
- `frontend/src/pages/` - Route pages
- `frontend/src/hooks/` - Custom React hooks
- `frontend/src/store/` - State management

### Shared
- `.env` - Environment variables (port, secrets, database path)
- `package.json` - Root package.json with scripts
- `database/data.db` - SQLite database (created on first run)

## Development Workflow

1. Install dependencies: `npm install`
2. Create `.env` from `.env.example`
3. Start backend: `npm run server` (or `npm run dev` for dev)
4. Start frontend: `npm start` (or `npm run dev` for dev)

### Scripts
- `npm start` - Start frontend
- `npm run server` - Start backend
- `npm run dev` - Start both in dev mode
- `npm run build` - Build for production
- `npm run pm2:start` - Start with PM2

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /api/players` | Get all players |
| `POST /api/players` | Create player (GM only) |
| `GET /api/shop` | Get shop inventory |
| `GET /api/bestiary` | Get bestiary data |
| `GET /api/rules/search` | Search rules |

### Authentication
- Sessions use HTTP-only cookies
- GM endpoints require `x-gm-secret` header
- Passwords hashed with bcrypt

## Code Style

- Use TypeScript for all new code
- Follow Airbnb JavaScript style guide
- Use ESLint for linting
- Maximum 100 character line length
- Functional React components with hooks

## Security Considerations

- Session cookies are HTTP-only
- Passwords hashed with bcrypt
- SQL queries use parameterized statements
- Rate limiting enabled (100 req/min)
- CORS configured for allowed origins
- Input validation on all endpoints

## Database

- SQLite by default
- Schema created automatically on first run
- Tables: players, items, inventory, sessions, webhooks
- Database path configurable via `DATABASE_PATH` env var
- Backups in `database/backups/`

## Frontend Components

Main component locations:
- `Shop/` - Shop and inventory components
- `Bestiary/` - Creature reference components
- `Rules/` - Rules database components
- `Sessions/` - Session tracking components
- `Players/` - Player management (GM only)

## Common Tasks

### Adding a New API Endpoint
1. Create route file in `backend/src/routes/`
2. Add controller in `backend/src/controllers/`
3. Register route in `server.js`
4. Add tests in `backend/src/routes/__tests__/`

### Adding a New Frontend Component
1. Create component in `frontend/src/components/`
2. Add TypeScript interface for props
3. Use existing CSS patterns
4. Test in browser

### Adding a Database Model
1. Create model in `backend/src/models/`
2. Define schema with `sequelize`
3. Add indexes for frequent queries
4. Write migration if needed

## Testing

- Backend tests: `npm test`
- Frontend tests: `cd frontend && npm test`
- E2E tests: `npm run test:e2e`

## Documentation

Full documentation is in `docs/`:
- `SUMMARY.md` - Documentation index
- `quick-start.md` - Installation guide
- `user-guide.md` - User documentation
- `api.md` - API reference
- `developer-guide.md` - Contributing guide
- `security.md` - Security best practices
- `troubleshooting.md` - Common issues
- `pm2.md` - Production deployment

## Environment Variables

```env
PORT=5000              # Backend server port
SESSION_SECRET=...    # Session encryption key
X_GM_SECRET=...       # GM authentication secret
DATABASE_PATH=./database/data.db  # SQLite path
NODE_ENV=development   # env: development|production
```

## Getting Help

1. Check documentation in `docs/`
2. Review code examples in the codebase
3. See open issues on GitHub
4. Create new issue for questions