leagues-tools/CLAUDE.md

Leagues Tools

OSRS (Old School RuneScape) League tracker and planning application. Allows users to track League tasks, unlocks, planning, and group ironman progress via RuneLite plugin integration.

Tech Stack

Frontend (os-league-tools-master/)

• React 18.3 with React Router DOM 6.28
• Redux Toolkit for state management
• TailwindCSS 3.0 for styling
• Webpack 5 for bundling

Backend (server/)

• Hono - lightweight web framework on Node.js
• TypeScript (ES2022 target)
• Prisma 6.2 ORM with SQLite database
• bcrypt for password hashing
• Nodemailer for emails
• Blake2b for token hashing

Project Structure

leagues-tools-dev/
├── os-league-tools-master/     # React frontend
│   ├── src/
│   │   ├── App.js              # Main entry, routing
│   │   ├── client/             # API client modules
│   │   ├── components/         # React components
│   │   ├── pages/              # Page components
│   │   ├── store/              # Redux slices
│   │   └── hooks/              # Custom hooks
│   └── build/                  # Production build output
│
├── server/                     # Hono backend
│   ├── src/
│   │   ├── index.ts            # Server entry point
│   │   ├── app.ts              # Hono app setup
│   │   ├── db.ts               # Prisma client
│   │   ├── routes/             # API route handlers
│   │   ├── middleware/         # Auth middleware
│   │   └── utils/              # Helpers (email, password, blake2)
│   └── prisma/schema.prisma    # Database schema
│
└── ecosystem.config.js         # PM2 deployment config

Commands

Frontend

cd os-league-tools-master
npm run dev          # Start dev server (port 3000)
npm run build        # Production build

Backend

cd server
npm run dev          # Start with hot reload (tsx watch)
npm run build        # Compile TypeScript
npm run db:push      # Push schema to database
npm run db:migrate   # Run migrations
npm run db:generate  # Generate Prisma client

PM2 (Root)

npm run start        # Start all PM2 apps
npm run stop         # Stop all apps
npm run logs         # View logs

Database Schema (Key Models)

• User - Auth accounts with role (USER/ADMIN), sessions, characters
• Character - User's OSRS characters with RSN, stores tasks/unlocks/notes as JSON
• Session - Cookie-based sessions (7-day TTL)
• Group - Group Ironmen tracking with Blake2b hashed token
• Member - Group member data (stats, inventory, equipment, bank, quests)
• HiscoresCache - Cached OSRS hiscores (5-min TTL)

API Routes

All routes prefixed with /api:

Route	Purpose
/register, /login, /logout	Auth
/me, /auth/status	Current user
/forgot-password, /reset-password	Password reset
/characters	User character CRUD
/group/:name/*	Group data (RuneLite plugin)
/hiscores/:rsn	OSRS hiscores with caching
/admin/*	Admin user management
/create-group, /ge-prices	Public endpoints

Authentication

• Session-based: HTTP-only secure cookies, 7-day TTL
• Group tokens: Blake2b-256 hashed, used by RuneLite plugin
• Roles: USER (default), ADMIN (access to /api/admin/*)

Middleware in server/src/middleware/:

• session.ts - requireAuth, requireAdmin
• groupAuth.ts - RuneLite token validation

Environment Variables

Backend expects (via .env or ecosystem.config.js):

• PORT - Server port (3001 default)
• DATABASE_URL - SQLite path (file:./data.db)
• CORS_ORIGINS - Allowed origins (comma-separated)
• SMTP_HOST, SMTP_PORT, SMTP_FROM - Email config
• FRONTEND_BUILD_PATH - Path to React build

Frontend uses:

• REACT_APP_RELDO_URL - Override API endpoint
• REACT_APP_GA_MID - Google Analytics ID

Key Patterns

1. JSON Storage: Complex data (tasks, unlocks) stored as JSON strings in SQLite
2. Graceful Fallbacks: Hiscores returns stale cache if OSRS API fails
3. Character Active State: Only one character active per user
4. Bulk Sync: Merges local client data with server on login
5. SPA Routing: Backend serves index.html for non-API routes

Ports

Service	Dev	Prod
Frontend	3000	(served by backend)
Backend	3003	3002

Important Files

• server/src/app.ts - All route mounting, CORS, middleware
• server/prisma/schema.prisma - Full database schema
• os-league-tools-master/src/App.js - Frontend routing
• os-league-tools-master/src/client/ - API client functions
• ecosystem.config.js - PM2 deployment configuration