BMHKMS

Modern management system for the "BANGMOD HACKATHON" event — streamlining event coordination, registration, and operations.

Getting Started

Prerequisites

• Bun runtime (v1.3.5 or later)
• PostgreSQL database (or Docker for local development)

Installation

First, install the dependencies:

bun install

Environment Variables

Create a .env file in apps/server/ with the following required variables:

Server Environment Variables:

• DATABASE_URL - PostgreSQL connection string
• BETTER_AUTH_SECRET - Secret key for Better Auth (minimum 32 characters)
• BETTER_AUTH_URL - Base URL for authentication (e.g., http://localhost:3000)
• CORS_ORIGIN - Allowed CORS origin URLs (e.g., http://localhost:3001,http://localhost:3002)
• NODE_ENV - Environment mode (development, production, or test)

Web Environment Variables: Create a .env file in apps/web/ and apps/staff/ with:

• VITE_SERVER_URL - Backend API URL (e.g., http://localhost:3000)

Database Setup

This project uses PostgreSQL with Drizzle ORM.

Option 1: Using Docker (Recommended for Local Development)

Start a PostgreSQL database using Docker Compose:

bun run db:start

This will start a PostgreSQL container with the following defaults:

• Database: bmhkms
• User: postgres
• Password: password
• Port: 5432

Update your apps/server/.env file with:

DATABASE_URL=postgresql://postgres:password@localhost:5432/bmhkms

Option 2: Using Existing PostgreSQL

1. Make sure you have a PostgreSQL database set up.
2. Update your apps/server/.env file with your PostgreSQL connection details.

Apply Schema

Apply the schema to your database:

bun run db:push

Database Commands

• bun run db:push - Push schema changes to database
• bun run db:generate - Generate Drizzle migration files
• bun run db:migrate - Run database migrations
• bun run db:studio - Open Drizzle Studio UI for database management
• bun run db:start - Start PostgreSQL with Docker Compose
• bun run db:watch - Watch database with Docker Compose (foreground)
• bun run db:stop - Stop database container
• bun run db:down - Stop and remove database container

Then, run the development server:

bun run dev

Open http://localhost:3001 in your browser to see the web application. Open http://localhost:3002 in your browser to see the staff application. The API is running at http://localhost:3000.

Git Hooks and Formatting

This project uses Husky for git hooks and Ultracite (Biome) for code formatting and linting.

• bun run prepare: Initialize git hooks with Husky (run once after cloning)
• bun run check: Check for formatting and linting issues without fixing
• bun run fix: Automatically format and fix code with Ultracite

Git hooks are configured to run bun run fix on staged files before commits.

Project Structure

bmhkms/
├── apps/
│   ├── web/         # Frontend application (React + TanStack Start)
│   ├── staff/       # Staff application (React + TanStack Start)
│   ├── server/      # Backend API (Elysia, TRPC)
│   └── fumadocs/    # Documentation app (Fumadocs)
├── packages/
│   ├── api/         # API layer / business logic
│   ├── auth/        # Authentication configuration & logic
│   ├── db/          # Database schema & queries
│   ├── env/         # Environment variable validation
│   └── config/      # Shared TypeScript configuration

Available Scripts

Development

• bun run dev: Start all applications in development mode
• bun run dev:web: Start only the web application (port 3001)
• bun run dev:staff: Start only the staff application (port 3002)
• bun run dev:server: Start only the server

Build

• bun run build: Build all applications

Code Quality

• bun run check-types: Check TypeScript types across all apps
• bun run check: Check for formatting and linting issues
• bun run fix: Format and fix code with Ultracite (Biome)

Database

• bun run db:push: Push schema changes to database
• bun run db:generate: Generate Drizzle migration files
• bun run db:migrate: Run database migrations
• bun run db:studio: Open Drizzle Studio UI for database management
• bun run db:start: Start PostgreSQL with Docker Compose
• bun run db:watch: Watch database with Docker Compose (foreground)
• bun run db:stop: Stop database container
• bun run db:down: Stop and remove database container

Setup

• bun run prepare: Initialize git hooks with Husky