HackForge AI - Hackathon Operating System Bot

HackForge AI is a Discord-native operating system designed to automate and manage hackathons from start to finish. It manages registrations, teams, tracks, submissions, announcement generation, judging, and includes an AI assistant grounded in hackathon documentation using Retrieval-Augmented Generation (RAG).

---

🚀 Quick Start Guide

Prerequisites

• Node.js (v20+ recommended) and npm
• MongoDB (running locally on mongodb://localhost:27017)
• Docker Desktop (required to run the Supabase vector database)
• Ollama (installed on your Mac for local LLM inference)

---

Step 1: Clone & Configure

1. Create a .env file in the root folder (copy from .env.example).
2. Add your Discord Bot Token and Client ID.
3. Enable Developer Mode in Discord, copy your Server ID, and set DISCORD_GUILD_ID (for instant slash command updates).
4. Copy your Discord User ID and paste it in SUPER_ADMIN_IDS to give yourself administrative access.

---

Step 2: Spin Up Databases and Models

1. Start Docker Desktop. Ensure the local Supabase container is up (it runs on port 54321 and 54323).
2. Copy the actual local Supabase anon/service keys from your Supabase setup into your .env.
3. Start Ollama and download the Llama 3.2 model:

   ollama pull llama3.2

---

Step 3: Install & Start

1. Install Node dependencies:

   npm install

2. Register slash commands with your Discord server:

   npm run register-commands

3. Seed MongoDB with a default hackathon and tracks:

   npm run seed

4. Start the Express backend and Discord bot:

   npm run dev

5. Index Hackathon Rules into the RAG model: In a new terminal window, run:

   npm run upload-rules

---

🛠️ CLI/NPM Scripts

• npm run dev - Starts the development server using ts-node-dev.
• npm run register-commands - Registers slash commands with the Discord API.
• npm run seed - Prepopulates MongoDB with a test hackathon and tracks.
• npm run upload-rules - Uploads and indexes rules.txt into the RAG vector database.
• npm run build - Compiles TypeScript to JavaScript in dist/.
• npm start - Runs the compiled production code.
• npm test - Runs constraints validation tests.

---

📂 Project Structure

├── src/
│   ├── index.ts                 # App bootstrapping entry point
│   ├── app.ts                   # Express server routing & middlewares
│   ├── controllers/             # Express API controllers
│   ├── routes/                  # Express REST API routes
│   ├── database/                # MongoDB models, connection, and seed scripts
│   ├── discord/                 # Discord Bot logic and slash command handlers
│   └── services/                # Business logic (User, Team, Submissions, RAG)
├── rules.txt                    # Sample hackathon rules document
└── docker-compose.yml           # Runs the app and MongoDB containerized

For a detailed explanation of the project's architecture, database structure, and command routing, see explanation.md.