# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

CrowMate Nest is a community platform for **Headless Hazard**, an indie game. It consists of three monorepo sub-projects:

- **`nest-backend/`**: REST API (Express + TypeScript + PostgreSQL/Prisma)
- **`nest-front/`**: Public-facing community website (React + Vite, port 5173)
- **`nest-intra/`**: Staff-only internal portal (React + Vite, port 5174)

## Development Commands

### Backend (`nest-backend/`)
```bash
npm run dev           # ts-node-dev with auto-restart
npm run build         # TypeScript compilation to dist/
npm start             # Run compiled dist/index.js
npm run db:push       # Push Prisma schema changes (no migration file)
npm run db:migrate    # Create and apply a migration
npm run db:seed       # Run prisma/seed.ts
npm run db:studio     # Open Prisma Studio UI
```

### Frontend & Intranet (`nest-front/` and `nest-intra/`)
```bash
npm run dev           # Vite dev server
npm run build         # tsc + vite build
npm run lint          # ESLint
npm run preview       # Serve built output locally
```

### Environment Setup (Backend)
Copy `.env.example` to `.env`. Key variables:
```env
DATABASE_URL="postgresql://user:password@localhost:5432/nest_db"
JWT_SECRET="..."
PORT=3000
ADMIN_USERNAME / ADMIN_EMAIL / ADMIN_PASSWORD  # Auto-creates admin on startup
FRONT_ORIGIN / INTRA_ORIGIN                    # Production CORS origins
```

## Architecture

### Backend

**Tech**: Express 4, TypeScript 5.6, Prisma 5.22, PostgreSQL, JWT (7d), bcryptjs, Zod

**Request pipeline**: `authenticate()` → `requireStaff()` / `requireAdmin()` middleware, then route handler. JWT payload includes `{ userId, role, isAdmin }`.

**Route groups** (all under `/api/`):
- `auth`: login, register, /me
- `users`: CRUD + ban/unban (admin)
- `forum`: categories, threads (paginated), replies
- `bugs`: bug reports with uniqueCode (HH-XXXX), comments, internal notes, me-too voting
- `feed`: staff-only post feed
- `events`: announcements/updates/milestones/polls with voting
- `team`: team member profiles

**Key patterns**:
- All request bodies validated with Zod (`schema.safeParse()`)
- Response shaping via format helpers (`formatBug()`, `formatMember()`, etc.) in `src/lib/`
- Prisma eager-loads relations to avoid N+1
- Composite primary keys for `MeTooBug` (userId + bugReportId) and `PollVote` (userId + pollOptionId)

### Frontends (nest-front & nest-intra)

**Tech**: React 19, Vite 7, Tailwind CSS 4, React Router 6, TypeScript 5.9

Both frontends currently use **mock data** — no real API calls are wired up yet. Auth state is simulated with `MOCK_USERS` in `src/contexts/AuthContext.tsx` and persisted to `localStorage`.

- `nest-front` uses storage key `crowmate_auth_user`; all roles (`user`, `dev`, `com`) can log in
- `nest-intra` uses storage key `crowmate_intra_user`; blocks `role === 'user'` at login — staff only (`dev` / `com`)

**Shared structure** (both React projects mirror each other):
```
src/
  App.tsx              # Route definitions, React.lazy() imports
  contexts/
    AuthContext.tsx    # Auth state, role helpers, localStorage
  components/
    layout/            # Page wrapper with nav/sidebar
    shared/            # ProtectedRoute, PageLoader, DevRoleSwitcher
  pages/               # Page components (lazy loaded)
  types/index.ts       # All TypeScript interfaces
  utils/format.ts      # formatDate(), timeAgo(), truncate()
  data/mockData.ts     # Mock users, forum, bugs, events, team
```

**DevRoleSwitcher component** (nest-front only): floating UI to switch auth roles instantly without logging out — for development testing only.

### User Roles & Access

| Role | Access |
|------|--------|
| `user` | Public site features only |
| `dev` / `com` | Staff features (feed, intranet, bug triage, event creation) |
| `isAdmin: true` | User management, forum moderation, destructive operations |

### Data Models Summary

**User**: id, username, email, password (hashed), role, isAdmin, isBanned, avatarUrl

**Forum**: ForumCategory → ForumThread → ForumReply (cascade deletes on thread)

**BugReport**: uniqueCode (HH-XXXX auto-generated), severity, status, assignedTo; with BugComment (public), BugReportNote (staff-only), MeTooBug

**Events**: EventPost (type: announcement | update | milestone | poll) → Poll → PollOption → PollVote (composite key)

**Team**: TeamMember standalone profiles

### Docker

Each sub-project has its own `Dockerfile` and `docker-compose.yml`. The backend uses multi-stage builds; frontends use Nginx to serve the Vite build output (`nginx.conf` included).

## Key Implementation Notes

- The backend auto-creates an admin user on startup if `ADMIN_USERNAME/EMAIL/PASSWORD` env vars are set
- `prisma/seed.ts` populates sample data for development
- `nest-intra/public/services.json` defines quick-link cards for dev tools (GitHub, Plane, Jenkins, Proxmox, etc.) shown on the `/intranet/services` page
- Both frontends' `types/index.ts` and `utils/format.ts` are near-identical — changes often need to be mirrored
- When integrating real API calls, replace mock auth in `contexts/AuthContext.tsx` and mock data in `data/mockData.ts`