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

cd nest-backend
cp .env.example .env
# Edit .env with your database credentials
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

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

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

3. Internal Portal Setup

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:

# 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

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

License

Proprietary - CrowMate Team © 2026

---

For detailed architecture notes and development guidance, see CLAUDE.md