# 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
```bash
cd os-league-tools-master
npm run dev          # Start dev server (port 3000)
npm run build        # Production build
```

### Backend
```bash
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)
```bash
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