Skip to content

zereal-ai/suparank

Repository files navigation

Suparank

A web application for ranking items using a merge sort algorithm.

Development Setup

  1. Install dependencies:
npm install
  1. Copy .env.example to .env.local and fill in your environment variables:
cp .env.example .env.local
  1. Run the development server:
npm run dev

Deployment to Vercel

  1. Push your code to a GitHub repository

  2. Connect your repository to Vercel:

    • Go to Vercel
    • Click "New Project"
    • Import your GitHub repository
  3. Configure environment variables in Vercel:

    • Go to Project Settings > Environment Variables
    • Add the following variables for each environment (Production/Preview):
      # Production environment
      NEXT_PUBLIC_API_URL=https://api.your-domain.com  # Your production API URL
      AIRTABLE_API_KEY=your_airtable_api_key
      AIRTABLE_BASE_ID=your_airtable_base_id
      AIRTABLE_TABLE_ID=your_airtable_table_id
      
      # Preview environments (optional, for PR previews)
      NEXT_PUBLIC_API_URL=https://api-staging.your-domain.com  # Your staging API URL
      AIRTABLE_API_KEY=your_staging_airtable_api_key
      AIRTABLE_BASE_ID=your_staging_base_id
      AIRTABLE_TABLE_ID=your_staging_table_id
      
  4. Git Integration:

    • Production deployments are automatically triggered when pushing to the main branch
    • Preview deployments are created for each Pull Request
    • Development environment uses your local .env.local file
  5. Environment Behavior:

    • Production (main branch): Uses production environment variables
    • Preview (Pull Requests): Uses preview environment variables
    • Development (local): Uses .env.local variables
  6. Automatic Deployments:

    • Vercel automatically deploys your application
    • Each environment gets its own URL:
      • Production: your-app.vercel.app
      • Preview: your-app-git-pr-XX-username.vercel.app
      • Development: localhost:3000

Project Structure

  • src/app/ - Next.js application code
    • components/ - React components
    • api.ts - API client functions
    • page.tsx - Main application page
  • api/ - Backend API code
    • index.py - FastAPI application
    • suparank.py - Ranking logic

Features

  • Add items with title and description
  • Compare items in pairs
  • Keyboard navigation (left/right arrows)
  • Visual feedback for selections
  • Persistent rankings in Airtable
  • Reset ranking session

Setup

1. Airtable Setup

  1. Create a new Airtable base
  2. Create a table named "Items" with the following fields:
    • Title (Single line text)
    • Description (Long text)
    • Score (Number)
  3. Get your Airtable API key:
    • Go to your Airtable account
    • Under API section, generate a new API key if you don't have one
  4. Get your Base ID:
    • Open your Airtable base
    • Click "Help" -> "API Documentation"
    • Your base ID will be in the URL: airtable.com/[BASE_ID]/api/docs

2. Environment Setup

  1. Copy .env.example to .env:

    cp .env.example .env
  2. Fill in your Airtable credentials in .env:

    AIRTABLE_TOKEN=your_api_key_here
    AIRTABLE_BASE_ID=your_base_id_here
    NEXT_PUBLIC_API_URL=http://localhost:8000
    

3. Installation

  1. Install Python dependencies:

    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    pip install -r requirements.txt
  2. Install Node.js dependencies:

    npm install

4. Development

  1. Start the Python API server:

    npm run dev:api
  2. In a new terminal, start the Next.js frontend:

    npm run dev
  3. Open http://localhost:3000 in your browser

Usage

  1. Add items to rank through the web interface
  2. Compare items one by one
  3. View the final rankings sorted by score

License

MIT