Skip to content

Latest commit

 

History

History
142 lines (103 loc) · 3.31 KB

CONTRIBUTING.md

File metadata and controls

142 lines (103 loc) · 3.31 KB

Contributing to Genie 🧞

Welcome! Genie is a unified student utility dashboard built with SvelteKit (Frontend) and FastAPI + LlamaIndex (Backend). We manage this project as a monorepo using uv, bun, and jujutsu (jj).

1. Prerequisites

You need the following tools installed to run the project.

🍎 macOS (Homebrew)

# 1. Install core tools (uv, bun, just, jujutsu)
brew install uv bun just jujutsu

# 2. (Optional) If you prefer nvm/node for other things, you can skip. 
# We use Bun for this project.

🐧 Arch Linux

# Install everything from official repositories
sudo pacman -S uv bun just jujutsu

🪟 Ubuntu / Debian / WSL

# 1. Install uv (Python package manager)
curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh

# 2. Install Bun (JavaScript runtime)
curl -fsSL [https://bun.sh/install](https://bun.sh/install) | bash

# 3. Install Just (Task runner)
curl --proto '=https' --tlsv1.2 -sSf [https://just.systems/install.sh](https://just.systems/install.sh) | bash -s -- --to ~/bin
# Note: Ensure ~/bin is in your PATH.

# 4. Install Jujutsu (VCS)
# Option A: Via Cargo (Recommended if you have Rust)
cargo install --locked jujutsu

# Option B: Via Homebrew (Linuxbrew)
# brew install jujutsu

2. Setup Guide

Clone the Repository

We use jj (Jujutsu) co-located with Git.

# Create a directory and initialize
mkdir genie && cd genie
jj git init --colocate

# Add the remote
jj git remote add origin git@github.com:YOUR_USERNAME/genie.git

# Pull the latest main
jj git fetch
jj new main

Install Dependencies

We use a Justfile to handle setup commands for both the frontend and backend simultaneously.

# Install Backend (uv) and Frontend (Bun) dependencies
# You can run these manually if you prefer:

# Backend
cd backend
uv sync
cd ..

# Frontend
cd frontend
bun install
cd ..

3. Development

We use just to run the entire stack with a single command. This will spin up the FastAPI backend (port 8000) and the SvelteKit frontend (port 5173).

# Start both servers (Ctrl+C to stop both)
just dev

If you need to run them individually:

# Run only Backend
just backend

# Run only Frontend
just frontend

4. Project Structure

genie/
├── Justfile             # Command runner (Makefile alternative)
├── backend/             # Python / FastAPI / AI
│   ├── main.py          # API Entry point
│   ├── pyproject.toml   # Python dependencies (uv)
│   └── .venv/           # Virtual environment
├── frontend/            # SvelteKit / Tailwind
│   ├── src/             # UI Components
│   └── package.json     # Node dependencies (Bun)
└── data/                # Static data for RAG (CSVs, JSONs)

5. Version Control Workflow (Cheat Sheet)

Since we use jj, here are the common commands you will need:

# 1. Check repository status
jj st

# 2. Start a new feature (creates a new change on top of main)
jj new main

# 3. Save your work (Automatic, but use describe to name it)
jj describe -m "feat: add lecture schedule widget"

# 4. Push to GitHub
jj git push

# 5. Update your local repo with remote changes
jj git fetch
jj rebase -d main  # Rebase your current work on top of the new main