alex
a4cabbd2b8
- Remove OCR noise, credits, and duplicates from rules-database.json (288→255 rules) - Add clean_rules.py script for rule cleanup - Add CLAUDE.md, docs/, and update README with documentation links Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
171 lines
4.8 KiB
Markdown
171 lines
4.8 KiB
Markdown
# 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
|