dwroller/CLAUDE.md

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

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