Driller Platform - Complete Setup Guide

The Driller platform has three parts that work together:

Code Storage: GitHub holds all the code. When you push changes, Railway and Vercel automatically redeploy.

┌──────────────────────────────────────────────────────────────┐
│                         GitHub                                │
│                    (Your Code Repository)                     │
└──────────────────────────────────────────────────────────────┘
              │                              │
              ▼                              ▼
┌─────────────────────────┐    ┌─────────────────────────┐
│        Railway          │    │        Vercel           │
│    (Backend Server)     │    │   (Frontend Website)    │
│                         │    │                         │
│  • AI Grading           │◄───│  • Student Interface    │
│  • Save/Load Progress   │    │  • Problems & Grading   │
│  • Teacher Review       │    │  • Leaderboards         │
└─────────────────────────┘    └─────────────────────────┘
              │
              ▼
┌─────────────────────────┐
│       Supabase          │
│      (Database)         │
│                         │
│  • Student Progress     │
│  • Star Counts          │
│  • Time Tracking        │
└─────────────────────────┘
    

Create accounts on these 4 free services. Start with GitHub, then use "Sign in with GitHub" for the others (easier!).

Step 1: Create GitHub Account

GitHub stores your code and connects to the other services.

Step 2: Create Supabase Account

Click "Continue with GitHub" to link accounts.

Step 3: Create Railway Account

Click "Login with GitHub" to link accounts.

Step 4: Create Vercel Account

Click "Continue with GitHub" to link accounts.

"Forking" creates your own copy of the code that you control.

1. Open the original repository:
   Open lrsl-driller Repository
2. Click the "Fork" button (top-right corner of the page)
3. Keep defaults and click "Create fork"
4. Wait a few seconds - you'll be redirected to YOUR copy at:
   github.com/YOUR-USERNAME/lrsl-driller

Step 1: Create a New Project

1. Go to supabase.com/dashboard
2. Click "New Project"
3. Select your organization (or create one)
4. Fill in:
   • Project name: driller
   • Database Password: Click "Generate" for a strong password
   • Region: Choose the closest to you
5. Click "Create new project"
6. Wait 2-3 minutes for setup to complete

Step 2: Create Database Tables

1. In your Supabase project, click "SQL Editor" in the left sidebar
2. Click "New query"
3. Copy this entire SQL script and paste it:

-- =============================================
-- DRILLER PLATFORM DATABASE SCHEMA
-- Copy this entire block and run it in Supabase
-- =============================================

-- Users table
CREATE TABLE IF NOT EXISTS users (
  id BIGSERIAL PRIMARY KEY,
  username TEXT UNIQUE NOT NULL,
  real_name TEXT,
  role TEXT DEFAULT 'student',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Progress table
CREATE TABLE IF NOT EXISTS progress (
  id BIGSERIAL PRIMARY KEY,
  username TEXT NOT NULL,
  cartridge_id TEXT NOT NULL,
  mode_id TEXT NOT NULL,
  streaks JSONB DEFAULT '{}',
  star_counts JSONB DEFAULT '{"gold":0,"silver":0,"bronze":0,"tin":0}',
  unlocked_tiers JSONB DEFAULT '[]',
  total_problems INTEGER DEFAULT 0,
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(username, cartridge_id)
);

-- Leaderboard table
CREATE TABLE IF NOT EXISTS leaderboard (
  id BIGSERIAL PRIMARY KEY,
  username TEXT NOT NULL,
  cartridge_id TEXT NOT NULL,
  gold INTEGER DEFAULT 0,
  silver INTEGER DEFAULT 0,
  bronze INTEGER DEFAULT 0,
  tin INTEGER DEFAULT 0,
  total_problems INTEGER DEFAULT 0,
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(username, cartridge_id)
);

-- Teacher review queue
CREATE TABLE IF NOT EXISTS review_queue (
  id BIGSERIAL PRIMARY KEY,
  username TEXT NOT NULL,
  cartridge_id TEXT NOT NULL,
  mode_id TEXT NOT NULL,
  problem_context JSONB,
  answers JSONB,
  requested_at TIMESTAMPTZ DEFAULT NOW(),
  status TEXT DEFAULT 'pending',
  teacher_grades JSONB,
  reviewed_at TIMESTAMPTZ,
  reviewed_by TEXT
);

-- Time tracking: sessions
CREATE TABLE IF NOT EXISTS time_sessions (
  id BIGSERIAL PRIMARY KEY,
  session_id TEXT UNIQUE NOT NULL,
  username TEXT NOT NULL,
  session_start TIMESTAMPTZ NOT NULL,
  active_time_ms BIGINT DEFAULT 0,
  total_time_ms BIGINT DEFAULT 0,
  last_sync TIMESTAMPTZ DEFAULT NOW(),
  is_complete BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Time tracking: problems
CREATE TABLE IF NOT EXISTS time_problems (
  id BIGSERIAL PRIMARY KEY,
  session_id TEXT NOT NULL,
  username TEXT NOT NULL,
  problem_id TEXT,
  cartridge_id TEXT,
  mode_id TEXT,
  active_time_ms BIGINT DEFAULT 0,
  total_time_ms BIGINT DEFAULT 0,
  completed BOOLEAN DEFAULT FALSE,
  result JSONB,
  completed_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes for faster queries
CREATE INDEX IF NOT EXISTS idx_progress_username ON progress(username);
CREATE INDEX IF NOT EXISTS idx_leaderboard_cartridge ON leaderboard(cartridge_id);
CREATE INDEX IF NOT EXISTS idx_review_queue_status ON review_queue(status);
CREATE INDEX IF NOT EXISTS idx_time_sessions_username ON time_sessions(username);
CREATE INDEX IF NOT EXISTS idx_time_problems_username ON time_problems(username);

-- Enable Row Level Security
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE progress ENABLE ROW LEVEL SECURITY;
ALTER TABLE leaderboard ENABLE ROW LEVEL SECURITY;
ALTER TABLE review_queue ENABLE ROW LEVEL SECURITY;
ALTER TABLE time_sessions ENABLE ROW LEVEL SECURITY;
ALTER TABLE time_problems ENABLE ROW LEVEL SECURITY;

-- Allow all operations (for simplicity)
CREATE POLICY "Allow all on users" ON users FOR ALL USING (true);
CREATE POLICY "Allow all on progress" ON progress FOR ALL USING (true);
CREATE POLICY "Allow all on leaderboard" ON leaderboard FOR ALL USING (true);
CREATE POLICY "Allow all on review_queue" ON review_queue FOR ALL USING (true);
CREATE POLICY "Allow all on time_sessions" ON time_sessions FOR ALL USING (true);
CREATE POLICY "Allow all on time_problems" ON time_problems FOR ALL USING (true);

4. Click the "Run" button (or press Ctrl+Enter)
5. You should see "Success. No rows returned" - this is correct!

Step 3: Get Your Project URL and API Key

1. Click "Project Settings" (gear icon in bottom-left)
2. Click "API" in the settings menu (under Configuration)
3. Find and copy these two values:
   • Project URL - looks like: https://abcdefghijk.supabase.co
   • anon public key (under "Project API keys") - a long string starting with eyJ...

Step 1: Create Railway Project from GitHub

1. Go to railway.app/new
2. Click "Deploy from GitHub repo"
3. If prompted, authorize Railway to access your GitHub
4. Find and select your lrsl-driller repository
5. Click "Deploy Now"

Railway will start building - this takes about 1 minute. It will likely fail the first time - that's okay! We need to configure it.

Step 2: Configure the Server

1. Click on your service (the purple box with your repo name)
2. Go to the "Settings" tab
3. Scroll to "Source" section
4. Set "Root Directory" to: railway-server
5. Scroll to "Deploy" section
6. Set "Custom Start Command" to: node server.js

Step 3: Add Environment Variables

1. Go to the "Variables" tab
2. Click "+ New Variable"
3. Add these two variables:

Railway will automatically redeploy after adding variables.

Step 4: Generate a Public URL

1. Go to the "Settings" tab
2. Scroll to "Networking" section
3. Click "Generate Domain"
4. Copy your new URL (looks like: https://lrsl-driller-production-xxxx.up.railway.app)

Step 1: Import Project

1. Go to vercel.com/new
2. Find your lrsl-driller repository
3. Click "Import"

Step 2: Configure Environment Variable

Before deploying, expand "Environment Variables" and add:

3. Click "Deploy"
4. Wait 1-2 minutes for the build to complete

Verify Everything Works

1. Open your Vercel URL in a new tab
2. You should see the Driller homepage with cartridge options
3. Click on "LSRL Interpretation" or any cartridge
4. Enter a test username (e.g., "testuser")
5. Try answering a problem and clicking "Grade"
6. Refresh the page - your progress should be saved!

Quick Test Checklist

• Page loads without errors
• Can enter username and start problems
• Grading shows feedback (E/P/I)
• Stars and streaks update
• Progress persists after page refresh

AI grading provides intelligent feedback on free-response answers. Without it, the app uses keyword matching (still works, just less sophisticated).

Get a Google Gemini API Key

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the key that appears

Get a Groq API Key (Backup)

1. Go to Groq Console
2. Create an account
3. Navigate to "API Keys"
4. Create and copy a new key

Add API Keys to Railway

1. Go back to your Railway dashboard
2. Click on your project, then your service
3. Go to the "Variables" tab
4. Add these new variables:

When you're ready to create your own cartridges or customize the app, use Project IDX - Google's free cloud IDE.

Open Your Repository in Project IDX

1. Go to idx.google.com
2. Click "Get started" and sign in with Google
3. Click "Import a repo"
4. Paste YOUR forked repository URL:
   https://github.com/YOUR-USERNAME/lrsl-driller
5. Click "Import"
6. Wait 2-3 minutes for the environment to build

Making Changes and Deploying

When you edit files in Project IDX and want to deploy:

1. Make your changes in the editor
2. Open the Terminal (View → Terminal or Ctrl+`)
3. Run these commands:

git add .
git commit -m "Description of your changes"
git push

That's it! Railway and Vercel will automatically detect the push and redeploy within 1-2 minutes.

Creating Your Own Cartridge

See the CARTRIDGE-DEVELOPMENT-GUIDE.md file in your repository for detailed instructions on creating lessons.

Quick summary - create a folder in cartridges/ with these 4 files:

• manifest.json - Defines inputs, modes, hints
• generator.js - Generates random problems
• grading-rules.js - Scores student answers
• ai-grader-prompt.txt - (Optional) AI grading instructions

"Failed to fetch" or Network Errors

• Check Railway dashboard - is your service running (green status)?
• Verify the VITE_API_URL in Vercel matches your Railway URL exactly
• Make sure the URL starts with https://
• Try redeploying on Vercel: Deployments → ... → Redeploy

"Database connection failed" in Railway Logs

• Double-check SUPABASE_URL and SUPABASE_ANON_KEY in Railway variables
• Ensure SUPABASE_URL is the Project URL (e.g., https://abcdefghijk.supabase.co)
• Ensure SUPABASE_ANON_KEY is the anon public key (starts with eyJ...)
• Check Supabase dashboard - project should show "Active" status

Railway Build Fails

• Check that Root Directory is set to railway-server
• Check that Start Command is set to node server.js
• View the build logs for specific error messages

Progress Not Saving

• Open browser console (F12) and check for errors
• Verify Railway is running and connected to Supabase
• Check that you entered a username before starting

AI Grading Not Working

• Make sure GEMINI_API_KEYS or GROQ_API_KEYS are set in Railway
• The app falls back to keyword grading if AI fails - this is normal
• Check Railway logs for API errors

Still Stuck?

Include: which step you're on, the exact error message, and screenshots if possible.

Video Tutorials

Watch these step-by-step walkthrough videos:

• Video 1: Account Setup & GitHub Fork - Covers Parts 1-2
• Video 2: Supabase Database Setup - Covers Part 3
• Video 3: Railway Backend Deployment - Covers Part 4
• Video 4: Vercel Frontend & Testing - Covers Parts 5-6
• Video 5: AI Grading Setup - Covers Part 7
• Video 6: Project IDX & Code Editing - Covers Part 8