Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fmoraga01/SpinAI/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running SpinAI on your local machine from a clean clone to a fully working app. By the end you will have the Next.js dev server running, your Supabase database seeded with the correct schema, and the roulette ready to assign your first facilitator.

​
Prerequisites

Before you start, make sure you have the following:
  • Node.js 18 or later — SpinAI uses Next.js 16 and React 19, which require Node 18+.
  • A Supabase account — Create a free project at supabase.com. You will need the project URL and the anon/public key.
  • A Gmail account with an App Password — SpinAI sends email via Gmail SMTP. You must generate an App Password in your Google Account security settings; your regular Gmail password will not work.

​
Setup Steps

1

Clone the repository

Clone the SpinAI repository from GitHub and move into the project directory.
git clone https://github.com/fmoraga01/SpinAI.git && cd SpinAI
2

Install dependencies

Install all Node.js dependencies with npm.
npm install
This installs Next.js 16, @supabase/supabase-js, nodemailer, jose for JWT handling, and the rest of the packages listed in package.json.
3

Create your Supabase project and run migrations

In your Supabase dashboard, create a new project, then run the initial migration to create all required tables (members, assignments, templates, assignment_logs) along with their indexes and Row Level Security policies.Navigate to SQL Editor in your Supabase dashboard and paste the contents of the migration file:
supabase/migrations/20260702000000_esquema_inicial.sql
Alternatively, if you have the Supabase CLI installed, run:
supabase db push
The migration enables the pgcrypto extension, creates all four tables with UUID primary keys, and applies anon full access RLS policies so the app can read and write using the public anon key. The members table includes an email column from the start, enabling per-member email notifications without any additional schema changes.
4

Create your .env.local file

Create a .env.local file in the root of the project and fill in all required variables. You can copy the block below as a starting template.
# ── Supabase ──────────────────────────────────────────────────────────────
# Found in your Supabase project under Settings → API
NEXT_PUBLIC_SUPABASE_URL=https://<your-project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-public-key>

# ── Auth ──────────────────────────────────────────────────────────────────
# The PIN your team will enter to access the app (case-insensitive)
PIN=your-team-pin

# Secret used to sign and verify 30-day session tokens (HS256)
JWT_SECRET=replace-with-a-long-random-string

# ── Email ─────────────────────────────────────────────────────────────────
# Gmail address used as the sender for all notifications
GMAIL_USER=yourteam@gmail.com

# Gmail App Password — NOT your regular Gmail account password
GMAIL_PASS=xxxx-xxxx-xxxx-xxxx

# ── Cron ──────────────────────────────────────────────────────────────────
# Shared secret sent in the x-cron-secret header by GitHub Actions
CRON_SECRET=replace-with-another-long-random-string
Generate a cryptographically strong value for JWT_SECRET (and CRON_SECRET) with:
openssl rand -base64 32
Run this command twice to get two distinct secrets.
GMAIL_PASS must be a Gmail App Password, not your Google account password. Generate one at Google Account → Security → 2-Step Verification → App passwords. Your normal password will be rejected by Gmail SMTP.
5

Start the development server

Run the Next.js development server.
npm run dev
Open http://localhost:3000 in your browser. You should see the SpinAI PIN gate.
6

Enter your PIN and spin the roulette

Enter the PIN you set in PIN to authenticate. On successful entry, the app creates a signed JWT cookie (spinai_token) valid for 30 days and redirects you to the home page.From the home page, add your team members, then click Spin to let the roulette randomly assign a facilitator to an upcoming Friday. The assignment is saved immediately to Supabase and will appear on the calendar.

​
What’s Next

You’re up and running. To learn how each environment variable works in depth — including the PIN/JWT authentication model, cookie settings, and how to wire up the GitHub Actions cron job — see the configuration reference. → Environment Variables and Configuration Reference

Build docs developers (and LLMs) love

Get started for freeTalk to us