Nest/README.md

# CrowMate Nest

Community platform monorepo for **Headless Hazard**, an indie game project.

## Project Structure

This is a TypeScript monorepo containing three interconnected applications:

```
nest-backend/    # REST API (Express + PostgreSQL + Prisma)
nest-front/      # Public community website (React + Vite)
nest-intra/      # Staff-only internal portal (React + Vite)
```

## Prerequisites

- **Node.js** 18+ and npm
- **PostgreSQL** 14+
- **Docker** (optional, for containerized deployment)

## Quick Start

### 1. Backend Setup

```bash
# from repository root
cp .env.example .env
# Edit .env with your credentials

cd nest-backend
npm install
npm run db:push        # Initialize database schema
npm run db:seed        # Populate with sample data
npm run dev            # Start dev server (http://localhost:3000)
```

#### Backend Environment Variables

```env
API_HOST_PORT=3001
DATABASE_URL="postgresql://user:password@localhost:5432/nest_db"
JWT_SECRET="your-secret-key"
PORT=3000
ADMIN_USERNAME="admin"
ADMIN_EMAIL="admin@example.com"
ADMIN_PASSWORD="changeme"
FRONT_ORIGIN="http://localhost:5173"
INTRA_ORIGIN="http://localhost:5174"
```

### 2. Public Frontend Setup

```bash
cd nest-front
npm install
npm run dev           # Start dev server (http://localhost:5173)
```

### 3. Internal Portal Setup

```bash
cd nest-intra
npm install
npm run dev           # Start dev server (http://localhost:5174)
```

## Development Commands

### Backend (`nest-backend/`)

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with auto-reload |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm start` | Run compiled production build |
| `npm run db:push` | Push schema changes (no migration) |
| `npm run db:migrate` | Create and apply migration |
| `npm run db:seed` | Populate database with sample data |
| `npm run db:studio` | Open Prisma Studio UI |

### Frontends (`nest-front/` and `nest-intra/`)

| Command | Description |
|---------|-------------|
| `npm run dev` | Start Vite dev server |
| `npm run build` | Build for production |
| `npm run lint` | Run ESLint |
| `npm run preview` | Preview production build |

## Tech Stack

### Backend
- **Runtime**: Node.js + Express 4
- **Language**: TypeScript 5.6
- **Database**: PostgreSQL + Prisma ORM 5.22
- **Auth**: JWT (7-day expiry) + bcryptjs
- **Validation**: Zod

### Frontends
- **Framework**: React 19
- **Build Tool**: Vite 7
- **Language**: TypeScript 5.9
- **Styling**: Tailwind CSS 4
- **Routing**: React Router 6

## Features

### Public Website (`nest-front`)
- User authentication & registration
- Community forum (categories, threads, replies)
- Bug reporting system with unique codes (HH-XXXX)
- Events & announcements
- Team member profiles
- Development studio page

### Staff Portal (`nest-intra`)
- Bug triage & management
- User moderation & management
- Event creation & management
- Staff feed posts
- Development services quick links
- **Access restricted to `dev` and `com` roles**

## User Roles

| Role | Access Level |
|------|-------------|
| `user` | Public site features only |
| `dev` | Developer staff features + intranet |
| `com` | Community manager features + intranet |
| Admin flag | User management, moderation, destructive operations |

## Docker Deployment

Each sub-project includes its own `Dockerfile` and `docker-compose.yml`:

```bash
# Build and run backend
cd nest-backend
docker-compose up --build

# Build and run frontend
cd nest-front
docker-compose up --build

# Build and run intranet
cd nest-intra
docker-compose up --build
```

Or use the root `docker-compose.yml` for orchestrating all services together.

## API Endpoints

All backend routes are prefixed with `/api/`:

- `/api/auth` - Login, register, current user
- `/api/users` - User management (admin)
- `/api/forum` - Categories, threads, replies
- `/api/bugs` - Bug reports, comments, me-too votes
- `/api/feed` - Staff feed posts
- `/api/events` - Announcements, updates, polls
- `/api/team` - Team member profiles

See `nest-backend/src/routes/` for detailed endpoint definitions.

## Database Schema

Key models:
- **User** - Authentication and profiles
- **ForumCategory** → **ForumThread** → **ForumReply**
- **BugReport** → **BugComment** / **BugReportNote** / **MeTooBug**
- **EventPost** → **Poll** → **PollOption** → **PollVote**
- **TeamMember** - Staff profiles
- **FeedPost** - Internal staff communications

See `nest-backend/prisma/schema.prisma` for the complete schema.

## Current Status

**Backend**: Fully functional API with all endpoints implemented.

**Frontends**: UI complete with mock data. Real API integration is pending — both `nest-front` and `nest-intra` currently use simulated auth and mock data defined in `src/contexts/AuthContext.tsx` and `src/data/mockData.ts`.

## Contributing

We welcome contributions from authorized team members and approved contributors! Please read our [Contributing Guidelines](./CONTRIBUTING.md) for detailed information on:

- Development workflow
- Coding standards
- Testing guidelines
- Commit message conventions
- Pull request process

Quick start for contributors:

1. Create a feature branch from `main`
2. Make your changes in the appropriate sub-project
3. Test locally with `npm run dev`
4. Run linting (`npm run lint` for frontends)
5. Submit a pull request following our PR template

## License

This project is proprietary software owned by the CrowMate Team. See the [LICENSE](./LICENSE) file for details.

Copyright © 2026 CrowMate Team. All rights reserved.